接口文档神器Swagger（下篇）

本文来自网易云社区

做者：李哲

2、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的插件开发等等。

3、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还提供不少开源项目和活跃的社区，若是遇到问题能够去寻求帮助。

4、总结

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

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

附（经常使用注解表）：

相关阅读：接口文档神器Swagger（上篇）

网易云大礼包：https://www.163yun.com/gift

本文来自网易云社区，经做者李哲受权发布

 

相关文章：
【推荐】 用SolrJ操做Solr作搜索（上篇）
【推荐】 【专家坐堂】四种并发编程模型简介
【推荐】 视觉设计师的进化