> 日常求赞，感谢老板。
>
现在的很多项目都是前后端分离的，后端提供接口，前端调用接口，在这个过程中一般后端会向前端提供一份接口文档，但是随着程序的调整，我们还要不断的去迭代接口文档，最后可能会搞出一堆，写起来比较耗时且在规范性上也很难要求。在这个前提下我们可以选择Swagger加入到我们的项目中。
Swagger提供了很多的功能，其中Swagger UI和Swagger Inspector使用的比较多
- Swagger UI：提供了一个UI页面描述项目中的接口（包括接口含义、uri、方法、参数、返回值和字段含义等）
- Swagger Inspector：提供了在线对接口进行测试的功能
我们这里的项目框架是Spring Boot
1.引入依赖io.springfoxspringfox-swagger22.9.2io.springfoxspringfox-swagger-ui2.9.2
@EnableSwagger2
@Configuration
public class SwaggerConfig {
private ApiInfo apiInfo() {
return new ApiInfoBuilder()
// 设置页面标题
.title("使用swagger2构建后端api接口文档")
// 设置联系人
.contact(new Contact("myname", "url", "email"))
// 描述
.description("欢迎访问后端接口文档，这里是描述信息")
// 定义版本号
.version("1.0").build();
}
@Bean
public Docket createRestApi() {
return new Docket(documentationType.SWAGGER_2).apiInfo(apiInfo()).select()
//接口所在的包
.apis(RequestHandlerSelectors.basePackage("com.example.swaggerdemo.controller"))
.paths(PathSelectors.any()).build();
}
}
至此，我们就可以访问http://localhost:8080/swagger-ui.html看到swagger为我们提供的在线调试和在线接口文档的页面了
但是，目前上面的描述信息还不够详细。我们可以通过下面的注解来完善对接口、参数、返回值等的描述
3.常用注解| 注解 | 标注位置和含义 | 属性以及取值含义 |
|---|---|---|
| @Api | 标注在接口类上，表示对此类接口的描述 | tags=“说明此类下接口的含义” |
| @ApiOperation | 标注在接口方法上，描述接口的用途 | value=“说明方法的用途、作用” notes=“方法的备注” |
| @ApiImplicitParams | 标注在请求的方法上，代表一组参数（运用于单体参数，不是javabean参数） | value = {@ApiImplicitParam…} |
| @ApiImplicitParam | 写在@ApiImplicitParams的value={}中，描述每个参数 | 见附3.1 |
| @ApiModel | 标注在javabean参数和响应对象上，描述javabean含义 | value=“描述对象含义” |
| @ApiModelProperty | 标注在javabean参数和响应对象属性上，描述属性含义 | name=“参数”,value=“含义”,required=true/false |
附3.1：
- name=“参数”
- value=“参数含义描述”
- required=true/false是否必传
- paramType=“参数位置”
- header：参数在请求头，通过@RequestHeader获取
- query：参数通过@RequestParam获取
- path：参数在restfull接口url上，通过@PathVariable获取
- dataType=“参数类型，如String等”
- defaultValue=“参数默认值”
举个栗子：
@Api(tags = "测试接口")
@RestController
public class TestController {
@ApiOperation(value = "我是test1接口",notes = "notes：我是test1")
@ApiImplicitParams(value = {
@ApiImplicitParam(name = "name",value = "姓名",required = true,paramType = "query",dataType = "String",defaultValue = "zll")
})
@GetMapping("test1")
public Object test1(String name) {
return "success" + name;
}
@ApiOperation(value = "我是test2接口",notes = "notes：我是test2")
@GetMapping("test2")
public Object test2(TestParamDTO testParamDTO) {
return "success" + testParamDTO.getName();
}
}
@Data
@ApiModel(value = "测试javabean参数")
public class TestParamDTO {
@ApiModelProperty(name = "name",value = "姓名",required = true)
private String name;
}
到这里已经完成了整个的整合，前端再让你出接口文档，直接url地址扔给她，潇洒转身离开。程序改动也不用重新写一份，改了哪里注解改一下就行了。
4.“你这页面好丑啊”“你这页面好丑啊，接口多了也不好找。。。。”
“线上调试，接口做了鉴权没token怎么办。。。。”
面对这些吐槽，下面介绍一个好看的ui：knife4j（https://gitee.com/xiaoym/knife4j） ，这是个人维护的ui项目很好的解决了上面的问题
引入knife4j只需要引入相应的依赖，其他的都不用修改，完美兼容
com.github.xiaoyminknife4j-spring-boot-starter2.0.2
可以把之前引入的swagger依赖都去掉了，这个依赖包含了所需的swagger依赖
这次访问线上接口文档的地址改成了：http://localhost:8080/doc.html
不仅优化了ui界面，而且在文档管理中为我们提供了全局参数、离线文档等功能，很值得推荐。
三、最后文章中的demo我已经上传到了gitee，需要的可以clone看一下：https://gitee.com/zhanglinlu/swagger-demo
点个赞啊亲
> 如果你认为本文对你有帮助，可以「在看/转发/赞/star」，多谢
>
> 如果你还发现了更好或不同的想法，还可以在留言区一起探讨下
