手机网站建设要素,凡科免费网站可以做推广吗,小白怎么做网页,漳州做网站喊多少钱本文来自网易云社区作者#xff1a;李哲二、Swagger-springmvc原理解析上面介绍了如何将springmvc和springboot与swagger结合#xff0c;通过简单配置生成接口文档#xff0c;以及介绍了swagger提供的一些注解。下面将介绍swagger是如何做到与springmvc结合#xff0c;自动…本文来自网易云社区作者李哲二、Swagger-springmvc原理解析上面介绍了如何将springmvc和springboot与swagger结合通过简单配置生成接口文档以及介绍了swagger提供的一些注解。下面将介绍swagger是如何做到与springmvc结合自动生成接口文档。项目添加完成maven依赖后会加入swagger的依赖包其中包括swagger- springmvcswagger-annotationsswagger-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文档时返回数据给前端uicore是整个处理过程的核心模块例如注解的解析model的处理一些处理过程中的策略等等ordering包中是用于处理页面显示接口时一些排序问题其中的class都继承了OrderingT类实现了ComparatorT接口paths包下了类主要是处理前端访问swagger接口时的路径问题plugin是swagger和spring结合的适配处理也是程序的入口相对spring来说swagger就像一个插件接入spring中scanners和readers两个包主要是处理注解的获取和扫描解析。swagger- springmvc包下的大致结构就是这样的看到这是不是觉得swagger没那么神奇了其实swagger做的两件最主要的事就是扫描解析注解变成相应的model前端请求接口文档时返回后台处理好的接口信息。马上就要进入程序入口了是不是有点激动呢可能有的人会问怎么知道Swagger PluginAdapter是程序的入口配置的文件不是SpringSwaggerConfig吗进入源代码就能找到答案下面来看下SwaggerPluginAdapter类这个类实现了ApplicationListenerContextRefreshedEvent接口这是一个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中使用swaggerswagger是如何在springmvc中发挥神奇功效的以及swagger的其他功能等。但是swagger也存在一些问题例如需要在后台代码中加一些注解过多的注解造成注解泛滥接口文档需要等到后台接口写好才能在前端展示而一般开发可能需要先定义好接口然后才开始写代码造成的流程混乱要很深入的了解swagger需要时间和精力对于忙业务的开发可能觉得不值得在上面花时间学习。其实对于这些问题都有很好的办法解决相比通过简单学习就能方便的获得接口信息而且不用反复更新文档是很值得的一件事。对于接口文档需要等后台开发完才能展示的问题可以先通过静态的文档书写方式先写文档之后再通过后台接口方式实现。通过上面的介绍我们了解到swagger是一个功能非常强大的工具如果能很好地利用这个工具将很大程度上提高我们的开发效率。虽然swagger之前也被爆出安全性问题但这个问题在后续版本中得到了修复所以赶快学习使用这个神器。由于时间仓促如果文中有错误请谅解。附常用注解表相关阅读接口文档神器Swagger上篇网易云大礼包https://www.163yun.com/gift本文来自网易云社区经作者李哲授权发布 相关文章【推荐】 用SolrJ操作Solr做搜索上篇【推荐】 【专家坐堂】四种并发编程模型简介【推荐】 视觉设计师的进化