2 swagger简介
Swagger是一款RESTFUL接口的文档在线自动生成+功能测试功能软件。
Swagger is used together with a set of open-source software tools to design, build, document, and use RESTful web services. Swagger includes automated documentation, code generation (into many programming languages), and test-case generation.
3 swagger-ui依赖
- 引入swagger原生依赖
springfox-swagger2和springfox-swagger2-ui- 引入国内Spring4All社区开发的依赖
swagger-spring-boot-starter
在pom.xml中添加如下依赖
<!--Swagger-UI API文档生产工具-->
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger2</artifactId>
<version>2.7.0</version>
</dependency>
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger-ui</artifactId>
<version>2.7.0</version>
</dependency>4 添加swagger配置类
详细信息见作者注解；
代码添加swgger-ui配置文件
注意：Swagger对生成API文档的范围有三种不同的选择
- 生成指定包下面的类的API文档
- 生成有指定注解的类的API文档
- 生成有指定注解的方法的API文档
给controller添加swagger注解
CommentGenerator为MyBatis Generator的自定义注释生成器，修改addFieldComment方法使其生成Swagger的@ApiModelProperty注解来取代原来的方法注释，添加addJavaFileComment方法，使其能在import中导入@ApiModelProperty，否则需要手动导入该类，在需要生成大量实体类时，是一件非常麻烦的事。
注释：CommentGenerator为方法生成的模型代码添加了相关ApiModelProperty注解，免去了手动添加的过程。为后面展示ApiModelProperty注解内部内容提供方便。
[外链图片转存失败,源站可能有防盗链机制,建议将图片保存下来直接上传(img-q45pgxwI-1602927431728)(/Users/fwd/Library/Application Support/typora-user-images/image-20201017171325408.png)]
下图为生成模型代码的截图，清晰可见注释内容。
5 操作展示
点击运行测试项目就可以查看整个swagger ui的界面，操作也十分简单，不再重复展示。
6 小结
swagger-ui很方便地完成了api的文档化和可操作化，而且文档风格也简单而优雅，国人开发的swagger-spring-boot-starter的启动器同样值得一试。
后续可以简单探究下swagger的api自动转化为web界面的相关原理。