【Swagger2】Spring Boot 整合 Knife4j 接口文档

╰+攻爆jí腚メ 2022-12-06 04:20 230阅读 0赞

## Knife4j 简介 ##

`Knife4j` 是 `swagger-bootstrap-ui` 的升级版，采用前后分离的模式，换为 `Knife4j`，为啥叫这名字，作者取名 `knife4j` 是希望她能像一把匕首一样小巧,轻量,并且功能强悍,更名也是希望把她做成一个为 `Swagger` 接口文档服务的通用性解决方案,不仅仅只是专注于前端。

## 引入依赖 ##

在 `pom.xml` 中引入 `Knife4j` 的依赖

<dependency>
        <groupId>com.github.xiaoymin</groupId>
         <artifactId>knife4j-spring-boot-starter</artifactId>
         <version>2.0.4</version>
     </dependency>

## 创建 Swagger 配置文件 ##

创建 `SwaggerConfiguration.java` 文件，创建 `springfox` 提供的 `Docket` 分组对象，代码如下：

@Configuration
    @EnableSwagger2
    @EnableKnife4j
    public class SwaggerConfiguration { 
    
    
        @Bean(value = "defaultApi2")
        public Docket defaultApi2() { 
            Docket docket=new Docket(DocumentationType.SWAGGER_2)
                    .apiInfo(apiInfo())
                    //分组名称
                    .groupName("2.X版本")
                    .select()
                    //这里指定Controller扫描包路径
                    .apis(RequestHandlerSelectors.basePackage("com.yuu.knife4j.boot"))
                    .paths(PathSelectors.any())
                    .build();
            return docket;
        }
    
        private ApiInfo apiInfo() { 
            return new ApiInfoBuilder()
                    .title("Spring Boot 整合 Knife4j 接口文档")
                    .description("# Spring Boot 整合 Knife4j 接口文档 APIs")
                    .termsOfServiceUrl("https://blog.csdn.net/qq_37581282")
                    .contact("yuu71@qq.com")
                    .version("1.0")
                    .build();
        }
    
    }

*  `@EnableSwagger2`：该注解是 `Springfox-swagger` 框架提供的使用 `Swagger` 注解，该注解必须加
 *  `@EnableKnife4j`：该注解是 `Knife4j` 提供的增强注解，Ui 提供了例如动态参数、参数过滤、接口排序等增强功能，如果你想使用这些增强供功能就必须加该注解，否者可以不同

## Controller 层注解说明 ##

@RestController
    @RequestMapping("user")
    @Api(tags = "用户模块")
    @ApiSupport(author = "Yuu", order = 1)
    public class UserController { 
    
        @Autowired
        private IUserService userService;
    
        /** * 用户列表 * * @param user 用户查询条件 * @param pageNo 第一页 * @param pageSize 每页的大小 * @return */
        @ApiOperation(value = "用户列表", notes = "获取用户列表")
        @ApiImplicitParams({ 
                @ApiImplicitParam(name = "pageNo", value = "分页-第几页", required = true, paramType = "query", dataType = "int"),
                @ApiImplicitParam(name = "pageSize", value = "分页-每页的大小", required = true, paramType = "query", dataType = "int")
        })
        @ApiResponses({ 
                @ApiResponse(code = 500, message = "服务器异常")
        })
        @GetMapping("list")
        public Response<List<User>> getUserList(@RequestParam Integer pageNo, @RequestParam Integer pageSize) { 
    
            // 模拟数据库查询用户列表
            List<User> users = userService.list(pageNo, pageSize);
    
            return Response.success(users);
        }
    }

**注解说明**

*  `@Api`: 作用于 `Controller` 类上，对请求类的说明
    
     *  `tags`：说明该类的作用
 *  `ApiSupport`：作用于 `Controller` 类上，用于描述模块的作者和排序
    
     *  `author`：该模块的作者
     *  `order`：该模块在接口文档的排序
 *  `@ApiOperation`：作用于方法上，对请求方法的描述
    
     *  `value`：说明方法的作用
     *  `notes`：方法的详细描述
 *  `@ApiImplicitParams`：作用于方法上，包含一组参数说明
    
     *  `@ApiImplicitParam`：作用于方法上， 对单个请求参数的说明
        
         *  `name`：参数名
         *  `value`：参数的说明、描述
         *  `required`：参数是否必填
         *  `paramType`：参数放在哪个地方
            
             *  `query`：对应 `@RequestParam`
             *  `header`：对应`@RequestHeader`
             *  `path (用于 Restful 接口）`：对应 `@PathVariable`
             *  `body（请求体）`：对应 `@RequestBody User user`
             *  `form（普通表单提交）`
         *  `dataType`：参数类型，默认 `String`
         *  `defaultValue`：参数的默认值
 *  `@ApiResponses`：对响应状态码的说明，包含一组响应说明
    
     *  `@ApiResponse`：对单个响应状态码的说明
        
         *  `code`：响应状态码
         *  `message`：返回消息

## Model 层注解说明 ##

@Data
    @ApiModel(description = "用户实体")
    public class User implements Serializable { 
    
        @ApiModelProperty(value = "用户ID")
        private Integer id;
    
        @ApiModelProperty(value = "用户名")
        private String username;
    
        @ApiModelProperty(value = "密码")
        private String password;
    
        @ApiModelProperty(value = "性别")
        private String sex;
    }

*  `ApiModel`：作用于实体类上，对实体类的描述
    
     *  `description`：描述实体类
 *  `ApiModelProperty`：作用于实体类属性上，对属性的描述
    
     *  `value` 描述属性

## 效果演示 ##

![在这里插入图片描述][20200912143135652.gif_pic_center]

## Github 完整 Demo 代码 ##

[Spring Boot 整合 Knife4j 接口文档][Spring Boot _ Knife4j]

[20200912143135652.gif_pic_center]: /images/20221123/cb7c2e5756a04c649baf2580e39824da.png
[Spring Boot _ Knife4j]: https://github.com/71yuu/knife4j-boot-demo