集成knife4j

1.引言：

在软件开发过程中，接口设计与接口文档编写是重要的一环，特别是在前后端分离的情况下，接口说明文档是开发人员之间的连接点。我们现在就是采用前后分离开发，以前我们用的RAP文档，都是后端手动来维护，有时候修改接口的时候，例如改一个字段名、加一个参数都不能做到实时更新。

2.swagger是什么？

Swagger 是一个规范且完整的框架，用于生成、描述、调用和可视化 RESTful 风格的 Web 服务。

• 支持 API 自动生成同步的在线文档：使用 Swagger 后可以直接通过代码生成文档，不再需要自己手动编写接口文档了，对程序员来说非常方便，可以节约写文档的时间去学习新技术。
• 提供 Web 页面在线测试 API：光有文档还不够，Swagger 生成的文档还支持在线测试。参数和格式都定好了，直接在界面上输入参数对应的值即可在线测试接口。

3.Knife4j介绍：

knife4j是github中为Java MVC框架集成Swagger生成Api文档的增强解决方案，前身是swagger-bootstrap-ui,取名knife4j是希望她能像一把匕首一样小巧,轻量,并且功能强悍!

• 简洁、美观
  相较于swagger页面更加美观，简洁。基于左右菜单布局方式，更符合操作习惯，文档清晰。
   
• 个性化配置
  个性化配置，支持接口地址，接口description属性、ui个性化配置功能
   
• 增强
  接口排序，swagger资源保护，导出Markdown、参数缓存等强大功能

4.搭建Knife4j

第一步：在maven项目的pom.xml中引入Knife4j的依赖包，代码如下：

1. 引入mes-knife4j依赖包

   <dependency>
    <groupId>com.hualala.supplychain</groupId>
    <artifactId>mes-knife4j</artifactId>
    <version>1.0.0-SNAPSHOT</version>
   </dependency>

2. 创建Swagger配置，代码如下： 

@Configuration
@EnableSwagger2
@EnableKnife4j
@Profile({"local","dohko"})
public class Knife4jConfig {

    @Bean
 public Docket baseApi(){
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo("mes系统基本档接口文档","mes系统前后端对接RESTful API接口使用，文档中可以查询及测试接口调用参数和结果","1.0"))
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.hualala.mes3.base.controller"))
                .paths(PathSelectors.any())
                .build()
                .groupName("mes系统基本档1.0").pathMapping("/");
 }
    @Bean
 public Docket pmcApi(){
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo("mes系统生产管理接口文档","mes系统前后端对接RESTful API接口使用，文档中可以查询及测试接口调用参数和结果","1.0"))
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.hualala.mes3.pmc.controller"))
                .paths(PathSelectors.any())
                .build()
                .groupName("mes系统生产管理1.0").pathMapping("/");
 }
    @Bean
 public Docket emcApi(){
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo("mes系统设备管理接口文档","mes系统前后端对接RESTful API接口使用，文档中可以查询及测试接口调用参数和结果","1.0"))
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.hualala.mes3.emc.controller"))
                .paths(PathSelectors.any())
                .build()
                .groupName("mes系统设备管理1.0").pathMapping("/");
 }
    @Bean
 public Docket qmsBaseApi(){
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo("质检系统基本档接口文档","质检系统前后端对接RESTful API接口使用，文档中可以查询及测试接口调用参数和结果","1.0"))
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.hualala.qms.base.controller"))
                .paths(PathSelectors.any())
                .build()
                .groupName("质检系统基本档1.0").pathMapping("/");
 }
    @Bean
 public Docket qmsQacApi(){
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo("质检系统接口文档","质检系统前后端对接RESTful API接口使用，文档中可以查询及测试接口调用参数和结果","1.0"))
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.hualala.qms.qac.controller"))
                .paths(PathSelectors.any())
                .build()
                .groupName("质检系统1.0").pathMapping("/");
 }
    private ApiInfo apiInfo(String title,String description,String version){
        return new ApiInfoBuilder()
                .title(title)
                .description(description)
                .version(version)
                .build();
 }
}

第三步：解决资源过滤

第四步：在接口上用swagger注释

5. 常用注解：

swagger2是通过扫描很多的注解来获取数据帮我们展示在ui界面上的，下面就介绍下常用的注解。

1、@Api()：用在请求的类上，表示对类的说明，也代表了这个类是swagger2的资源

参数：

tags：说明该类的作用，参数是个数组，可以填多个。
value="该参数没什么意义，在UI界面上不显示，所以不用配置"
description = "用户基本信息操作"

2、@ApiOperation()：用于方法，表示一个http请求访问该方法的操作

参数：

value="方法的用途和作用"    
notes="方法的注意事项和备注"    
tags：说明该方法的作用，参数是个数组，可以填多个。
格式：tags={"作用1","作用2"} 
（在这里建议不使用这个参数，会使界面看上去有点乱，前两个常用）

3、@ApiModel()：用于响应实体类上，用于说明实体作用

参数：

description="描述实体的作用"  

4、@ApiModelProperty：用在属性上，描述实体类的属性

参数：

value="用户名"  描述参数的意义
name="name"    参数的变量名
required=true     参数是否必选

5、@ApiImplicitParams：用在请求的方法上，包含多@ApiImplicitParam

6、@ApiImplicitParam：用于方法，表示单独的请求参数

参数：

name="参数ming" 
value="参数说明" 
dataType="数据类型" 
paramType="query" 表示参数放在哪里
    · header 请求参数的获取：@RequestHeader
    · query   请求参数的获取：@RequestParam
    · path（用于restful接口） 请求参数的获取：@PathVariable
    · body（不常用）
    · form（不常用） 
defaultValue="参数的默认值"
required="true" 表示参数是否必须传

7、@ApiParam()：用于方法，参数，字段说明 表示对参数的要求和说明

参数：

name="参数名称"
value="参数的简要说明"
defaultValue="参数默认值"
required="true" 表示属性是否必填，默认为false

8、@ApiResponses：用于请求的方法上，根据响应码表示不同响应

一个@ApiResponses包含多个@ApiResponse

9、@ApiResponse：用在请求的方法上，表示不同的响应

参数：

code="404"    表示响应码(int型)，可自定义
message="状态码对应的响应信息"   

10、@ApiIgnore()：用于类或者方法上，不被显示在页面上

11、@Profile({"local", "dohko"})：用于配置类上，表示只对开发和测试环境有用

6. UI展示：

本地url：http://localhost:8080/doc.html

童虎：http://dohko.mes3.supplychain.hualala.com/doc.html

访问页面加权控制

knife4j.basic.enable=true
## Basic认证用户名
knife4j.basic.username=mes
## Basic认证密码
knife4j.basic.password=mes123