mall学习02-整合swagger

1 相关链接

00-mall作者参考链接-文档-整合swagger

0-0mall作者参考链接-仓库-整合swagger

01-swagger io官方网站

02-swagger-ui git仓库地址

03-swagger-bootstrap-ui

04-SpringBoot整合Swagger实战

05-swagger-spring-boot-starter 开源项目

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依赖

1. 引入swagger原生依赖springfox-swagger2和springfox-swagger2-ui
2. 引入国内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的界面，操作也十分简单，不再重复展示。

http://localhost:8080/swagger-ui.html#/

6 小结

swagger-ui很方便地完成了api的文档化和可操作化，而且文档风格也简单而优雅，国人开发的swagger-spring-boot-starter的启动器同样值得一试。

后续可以简单探究下swagger的api自动转化为web界面的相关原理。