接口文档神器Swagger（下篇）

本文来自网易云社区

作者：李哲

二、Swagger-springmvc原理解析

上面介绍了如何将springmvc和springboot与swagger结合，通过简单配置生成接口文档，以及介绍了swagger提供的一些注解。下面将介绍swagger是如何做到与springmvc结合，自动生成接口文档。

项目添加完成maven依赖后会加入swagger的依赖包，其中包括swagger- springmvc，swagger-annotations，swagger-models几个依赖包。如下图所示：

其中，swagger-annotations是swagger提供给spring的注解包，上面说的注解基本都在这个包里面；swagger-models是swagger自己的model类，主要用于将注解解析成后面需要使用的model和一些model数据的处理。Swagger-springmvc是swagger接入spring的一个最重要的包，通过这个包的处理可以将添加的注解信息解析出来，自动生成接口需要的数据，最后通过url请求就能返回接口的信息，通过前端处理就可以在页面上看到接口的信息。下面将重点分析swagger-springmvc包下的文件，本文中分析的是1.0.2版本的swagger-springmvc，其他版本会存在差异，请自行研究。

下图是swagger-springmvc包结构，图中标红的两个类是swagger的入口类，根据包的名字大致能猜出各个模块的功能。这里先简单介绍下，annotation包下只有一个注解类ApiIgnore，用于忽略不被swagger处理；authorization包下主要用于处理需要认证的接口，添加认证信息；configuration主要处理配置相关的操作，其中包含了程序的配置SpringSwaggerConfig类，该类是swagger的默认配置类，也可以自己编写封装去修改配置（一般都会编写自己的配置类，设置一些api信息等）。Controller用于处理请求swagger文档时返回数据给前端ui；core是整个处理过程的核心模块，例如注解的解析，model的处理，一些处理过程中的策略等等；ordering包中是用于处理页面显示接口时，一些排序问题，其中的class都继承了Ordering<T>类，实现了Comparator<T>接口；paths包下了类主要是处理前端访问swagger接口时的路径问题；plugin是swagger和spring结合的适配处理，也是程序的入口，相对spring来说，swagger就像一个插件接入spring中；scanners和readers两个包主要是处理注解的获取和扫描解析。swagger- springmvc包下的大致结构就是这样的，看到这是不是觉得swagger没那么神奇了，其实swagger做的两件最主要的事就是：扫描解析注解变成相应的model，前端请求接口文档时返回后台处理好的接口信息。

马上就要进入程序入口了，是不是有点激动呢？可能有的人会问，怎么知道Swagger PluginAdapter是程序的入口？配置的文件不是SpringSwaggerConfig吗？进入源代码就能找到答案，下面来看下SwaggerPluginAdapter类：

这个类实现了ApplicationListener<ContextRefreshedEvent>接口，这是一个spring的接口，在spring的applicationcontext初始化完成后会执行onApplicationEvent方法，所以当spring启动后，swagger就会被启动。而SpringSwaggerConfig中使用了注解@configuration，会在spring启动时进行swagger配置，在配置的时候会根据用户自定义的配置进行设置，如果用户没有定义将用默认的配置。下面看下方法onApplicationEvent中的处理，如下图所示，程序会先去判断plugins是否存在，不存在直接使用默认的，如果配置中设置了plugin则使用配置中的SwaggerSpringMvcPlugin，最后都调用Swagger SpringMvcPlugin类的initialize方法。

SwaggerSpringMvcPlugin是swagger和spring框架核心的类。有好多可配置的属性，并且提供了相应的get与set方法。在该类中，初始化了SwaggerApiResourceListing类（用于扫描RequestMappingHandler方法）的属性。当调用initialize()方法的时候，调用的则是SwaggerApiResourceListing类的initialize()方法。

在initialize方法中主要做了两件重要的事，第一通过apiListingReferenceScanner扫描所有的spring请求路径（RequestMapping），过滤没在配置类中设置的include Patterns，将扫描结果转换为swagger自定义的model中。第二通过apiListingScanner类扫描第一步处理的每一个请求路径，根据swagger的注解扫描每一个路径对应的接口信息，最后将信息转换为swagger中model并保存在swaggerCache中方便以后使用。

接下来分析具体的扫描过程，ApiListingReferenceScanner中的scan方法是调用该类中的scanSpringRequestMappings方法。在该方法中主要做的是根据spring中的Request MappingHandlerMapping找出符合条件的路径并找出一些需要的信息保存起来。

ApiListingScanner类中主要扫描每个请求路径的具体接口信息，具体的扫描过程是通过命令模式执行。代码中的每一种reader对应一种具体要执行的命令操作，对所有的请求路径（RequestMapping）分别获取MediaType、接口描述、接口model等信息。其中，MediaTypeReader是解析请求的MediaType类型，ApiDescriptionReader是解析接口的信息，ApiModelReader是解析接口的model（即ApiModel标注的类）。解析完成后分别将这些信息保存起来。ApiDescriptionReader中主要处理了请求路径，然后通过ApiOperationReader去处理真正的接口信息。execute方法中可以看到分别去处理写在接口上的注解。

下面以一个OperationImplicitParametersReader为例介绍各种Reader是如何通过命令模式去处理对应的注解，其中通过AnnotationUtils.findAnnotation方法去查询Api ImplicitParams注解去获取接口上标注的参数信息，然后在继承类SwaggerParameterReader中的execute方法中被调用。

其他的注解也是通过这种方式被读取出来，最后会将这些信息保存到SwaggerCache中，到此swagger处理代码中的注解就已完成，当然过程中还有处理一些其他信息，例如，需要登录认证的信息，处理接口的请求路径以方便swagger本身请求接口时应用等等。但是这些处理好的信息是怎么能在前端页面显示的呢？接下来就研究下swagger如何在前端显示接口信息。在swagger的默认配置类中有个ComponentScan注解标注需要扫描的包com.mangofactory.swagger.controllers，在该包下有一个controller叫DefaultSwaggerController，代码如下：

可以看到，swagger根据处理好的路径对应返回相应的接口信息，从这里可以看到为什么解析的数据都放到SwaggerCache中，这样后台controller就可以返回请求的接口数据，通过前端页面的解析就能在前端显示接口的信息。下图是前端代码结构，通过index.html访问接口信息。

至此swagger-springmvc是如何做到通过简单注解配置就能实现自动生成接口文档信息的原理就讲完了，具体细节处理有兴趣者可以自己研究。现在看来swagger也没这么神奇了，但是其中用到的方法是值得我们学习使用的。例如，如何通过spring的方式获取spring中管理的一些资源，命令模式，结合spring的插件开发等等。

三、Swagger其他功能

除了上面介绍的功能外，swagger还有一些其他功能，打开swagger的官网

https://swagger.io/可以看到除了介绍的功能，还有一些其他工具。

这里简单介绍下swagger包含的其他功能，SwaggerEditor是一个swagger文档编辑工具，通过该工具可以实现静态接口文档编写，而且可以查看实时接口信息，上面一排按钮可以实现保存，生成相关代码等功能。如下图所示：

SwaggerCodeGen是一个代码生成的工具，即通过该工具可以实现根据接口信息生成各种语言的接口代码，可以生产前端、后台、移动端代码框架，可以通过 swagger- codegen-cli脚手架工具或者访问github地址：https://github.com/swagger-api/swagger- codegen根据提示操作，里面也有示例。生成前端、移动端的代码根据各语言通用的框架实现接口请求，例如android的代码中使用okhttp请求接口数据；同时可以通过静态接口文档生成服务器端代码，这样会根据文档中定义的接口信息和model生成相应的model和controller接口。通过SwaggerCodeGen生成的代码在大型项目中可能不太实用，因为里面很多代码不符合人们编码习惯，但是在快速开发的小型项目中可以尝试使用。

Swagger UI是展示接口页面的前端框架，接口信息就是通过这个框架显示出来的，所以不管是静态接口文档还是通过后台代码生成的接口信息都可以通过SwaggerUI来显示。上面介绍的swagger结合springmvc使用中使用的就是Swagger UI来显示接口页面。下图是swagger官网上的一个示例：

Swagger Inspector是一个测试接口工具，类似postman，主要用来测试请求返回情况，可以通过在线Swagger Inspector测试接口，基本测试是免费使用的。swagger还提供了一些高级功能，如安全扫描、复杂功能测试、load测试及监控数据等，可以根据需求付费使用。如下图所示，Swagger Inspector也可以保存请求历史，可以选择请求生成swagger文档。

除此之外，swagger还提供了SwaggerHub，这是一个swagger仓库，可以将文档上传保存，同时支持团队协作，在线编辑，安全线上查阅等功能。Swagger还提供很多开源项目和活跃的社区，如果遇到问题可以去寻求帮助。

四、总结

本文主要介绍了swagger的简介，如何在springmvc和springboot中使用swagger，swagger是如何在springmvc中发挥神奇功效的以及swagger的其他功能等。但是swagger也存在一些问题，例如需要在后台代码中加一些注解，过多的注解造成注解泛滥；接口文档需要等到后台接口写好才能在前端展示，而一般开发可能需要先定义好接口，然后才开始写代码造成的流程混乱；要很深入的了解swagger需要时间和精力，对于忙业务的开发可能觉得不值得在上面花时间学习。其实对于这些问题都有很好的办法解决，相比通过简单学习就能方便的获得接口信息而且不用反复更新文档是很值得的一件事。对于接口文档需要等后台开发完才能展示的问题，可以先通过静态的文档书写方式先写文档，之后再通过后台接口方式实现。

通过上面的介绍，我们了解到swagger是一个功能非常强大的工具，如果能很好地利用这个工具将很大程度上提高我们的开发效率。虽然swagger之前也被爆出安全性问题，但这个问题在后续版本中得到了修复，所以赶快学习使用这个神器。由于时间仓促，如果文中有错误请谅解。

附（常用注解表）：