共计 3359 个字符，预计需要花费 9 分钟才能阅读完成。
Spring Boot 优雅整合 Swagger2，主动生成在线文档
日常求赞，感激老板。
欢送关注公众号：其实是白羊。干货继续更新中 ……
一、前言
当初的很多我的项目都是前后端拆散的，后端提供接口，前端调用接口，在这个过程中个别后端会向前端提供一份接口文档，然而随着程序的调整，咱们还要一直的去迭代接口文档，最初可能会搞出一堆，写起来比拟耗时且在规范性上也很难要求。在这个前提下咱们能够抉择 Swagger 退出到咱们的我的项目中。
Swagger 提供了很多的性能，其中 Swagger UI 和 Swagger Inspector 应用的比拟多
- Swagger UI：提供了一个 UI 页面形容我的项目中的接口（包含接口含意、uri、办法、参数、返回值和字段含意等）
- Swagger Inspector：提供了在线对接口进行测试的性能
二、集成 Swagger
咱们这里的我的项目框架是 Spring Boot
1. 引入依赖
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger2</artifactId>
<version>2.9.2</version>
</dependency>
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger-ui</artifactId>
<version>2.9.2</version>
</dependency>2. 配置类
/**
* @Description swagger 配置文件
* @Author ZhangLinlu
* @Date 2020/10/10
**/
@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=” 参数默认值 ”
举个栗子：
/**
* @Description 测试接口
* @Author ZhangLinlu
* @Date 2020/10/10
**/
@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();
}
}
/**
* @Description 测试 javabean 参数
* @Author ZhangLinlu
* @Date 2020/10/10
**/
@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 只须要引入相应的依赖，其余的都不必批改，完满兼容
<dependency>
<groupId>com.github.xiaoymin</groupId>
<artifactId>knife4j-spring-boot-starter</artifactId>
<version>2.0.2</version>
</dependency>能够把之前引入的 swagger 依赖都去掉了，这个依赖蕴含了所需的 swagger 依赖
这次拜访线上接口文档的地址改成了：http://localhost:8080/doc.html
不仅优化了 ui 界面，而且在文档治理中为咱们提供了全局参数、离线文档等性能，很值得举荐。
三、最初
文章中的 demo 我曾经上传到了 gitee，须要的能够 clone 看一下：https://gitee.com/zhanglinlu/…
点个赞啊亲
如果你认为本文对你有帮忙，能够「在看 / 转发 / 赞 /star」，多谢
如果你还发现了更好或不同的想法，还能够在留言区一起探讨下
欢送关注公众号：「其实是白羊」干货继续更新中 ……
