Spring boot 集成swagger-ui 在线API文档生成自我实践记录

其中API列表被封装成ApiListing。ApiListing中又持有ApiDesciption集合引用，每个ApiDesciption都持有一个API集合的引用，Operation也就是具体的接口操作，内部包含了该接口对应的http方法、produces、consumes、协议、参数集、响应消息集等诸多元素。

springfox通过spring-plugin的方式将Plugin注册到Spring上下文中，然后使用这些plugin进行API的扫描工作，这里的扫描工作其实也就是构造Documentation的工作，把扫描出的结果封装成Documentation并放入到DocumentationCache内存缓存中，之后swagger-ui界面展示的API信息通过Swagger2Controller暴露，Swagger2Controller内部直接从DocumentationCache中寻找Documentation。

下面取部分plugin来看一下构造对应文档信息的过程：

从代码细节中入手，我们可以看到，入口处在@EnableSwagger2这个注解上，这个注解会导入一个配置类的Swagger2DocumentationConfiguration。

这个Swagger2DocumentationConfiguration做的事情如下：

1. 构造Bean。比如：HandlerMapping（HandlerMapping是springmvc中用于处理请求与handler(controller中的方法)之间映射关系的接口，springboot中默认使用的HandlerMapping是RequestMappingHandlerMapping），Swagger2DocumentationConfiguration配置类里构造的是PropertySourcedRequestMappingHandlerMapping，该类继承RequestMappingHandlerMapping。

2. import其它配置类，比如SpringfoxWebMvcConfiguration、SwaggerCommonConfiguration（SpringfoxWebMvcConfiguration配置类做的事情跟Swagger2DocumentationConfiguration类似）

3. 扫描指定包下的类，并注册到Spring上下文中

具体的API解析、扫描过程，这里不再展开细致的说明，可参考博文：https://yq.aliyun.com/articles/599809?utm_content=m_1000002417

总体上处理过程整理为下图：

三、为什么选择swagger？

手写Api文档的几个痛点

文档需要更新的时候，需要再次发送一份给前端，也就是文档更新交流不及时；
接口返回结果不明确；
不能直接在线测试接口，通常需要使用工具，比如postman；
接口文档太多，不好管理；

swagger的优势

使用Swagger UI生成的界面比Javadoc生成的界面美观
swagger可以实时同步API文档(代码修改后，文档同步修改)
swagger解析速度快，效率高(使用轻量级数据交换格式JSON)
对现有SpringMVC工程支持友好
Swagger可以充当前后端交流的重要桥梁，方便快捷。很实用。
Swagger项目允许你生产，显示和消费你自己的RESTful服务。不需要代理和第三方服务。

四、如何集成swagger到我们的项目？

说明：这里是在Spring boot的基础上集成swagger

添加maven依赖

<!-- 引入swagger依赖 -->
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger-ui</artifactId>
    <version>${swagger.version}&