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的依赖包，代码如下：
- 引入mes-knife4j依赖包
<dependency>
<groupId>com.hualala.supplychain</groupId>
<artifactId>mes-knife4j</artifactId>
<version>1.0.0-SNAPSHOT</version>
</dependency> - 创建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"})：用于配置类上，表示只对开发和测试环境有用
访问页面加权控制
knife4j.basic.enable=true
## Basic认证用户名
knife4j.basic.username=mes
## Basic认证密码
knife4j.basic.password=mes123
