今天我们来说说什么是Swagger？

就是把相关的信息存储在它定义的描述文件里面（yml或json格式）    
    
    
    
，再通过维护这个描述文件可以去更新接口文档 


     


     


     


  ，以及生成各端代码
    
    
    
  。而Springfox-swagger,则可以通过扫描代码去生成这个描述文件     


     


     


     
。

好处：

1    
    
    
    
、是一款让你更好的书写API文档的规范且完整框架 




 




 




 




。

2 


     


     


     


  、提供描述

 




 




 




 
、生产   

   

   

   

、消费和可视化RESTful Web Service

   

   

   

 。

3  

     

     

     

 、是由庞大工具集合支撑的形式化规范     

     

     

     。这个集合涵盖了从终端用户接口


  




  




  




  、底层代码库到商业API管理的方方面面  




  




  




  




。

4

 




 




 




 
，这个框架可以自动为你的业务代码生成restfut风格的api   

   

   

   

，而且还提供相应的测试界面  

     

     

     

 ，自动显示json格式的响应


  


  


  


。大大方便了后台开发人员与前端的沟通与联调成本     
     
     
     。

5


  




  




  




  ，说白了就是前端更快速指定后端的接口  


  


  


  


，我们后端可以联调接口的时候做别的事   




   




   




   



。

缺点：

如果使用的接口参数和返回值相对比较简单,即如果都是处理成单表操作的接口,那么使用swagger是明智选择,但是如果接口参数本身很复杂,接口的返回值同样非常复杂,那么swagger的作用就会缩小.因此复杂业务的接口文档或者wiki编写是必需的,简单的接口或者单表操作使用swagger



 



 



 



。

swagger进行API管理

目前 springfox 是一个很好的选择   
     
     
     
，它内部会自动解析Spring容器中Controller暴露出的接口



   




   




   




   ，并且也提供了一个界面用于展示或调用这些API                   。下图就是简单的一个使用springfox的API展示界面    




    




    




    


。

springfox的前身是swagger-springmvc 



 



 



 


，用于springmvc与swagger的整合



















。

如若在springboot项目中使用springfox                   ，需要3个步骤：

1  


  


  


  


、maven添加springfox依赖

2   
     
     
     
、启动类加上@EnableSwagger2注解

3



   




   




   




   、构造Docket bean用于展示API

配置完之后进入 http://{path}:{port}/swagger-ui.html 即可查看controller中的接口信息




    




    




    




   ，并按照Docket中配置的规则进行展示                  。

springfox实现原理

在分析springfox实现原理之前

















，首先看下springfox对文档Documentation的定义：

文档Documentation定义得很清晰                    ，主要由groupName(分组名) 



 



 



 


、basePath(contextPath)                   、apiListings(API列表集)




    




    




    




   、resourceListing(资源列表集)等属性组成     



     



     



     

。

其中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注解上   
     
     
     
，该注解会import一个配置类

Swagger2DocumentationConfiguration 




 




 




 




。

Swagger2DocumentationConfiguration做的事情：

1 


     


     


     


  、构造Bean

   

   

   

 。比如HandlerMapping



   




   




   




   ，HandlerMapping是springmvc中用于处理请求与handler(controller中的方法)之间映射关系的接口 



 



 



 


，springboot中默认使用的HandlerMapping是

RequestMappingHandlerMapping                   ，Swagger2DocumentationConfiguration配置类里构造的是PropertySourcedRequestMappingHandlerMapping




    




    




    




   ，该类继承RequestMappingHandlerMapping     

     

     

     。

2

 




 




 




 
、import其它配置类

















，比如

SpringfoxWebMvcConfiguration   

   

   

   

、SwaggerCommonConfiguration

3  

     

     

     

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

SpringfoxWebMvcConfiguration配置类做的事情跟Swagger2DocumentationConfiguration类似



     



     



     



   ，不过多了一步构造PluginRegistry过程  




  




  




  




。该过程使用@EnablePluginRegistries注解实现：

@EnablePluginRegistries注解是spring-plugin模块提供的一个基于Plugin类型注册PluginRegistry实例到Spring上下文的注解


  


  


  


。

@EnablePluginRegistries注解内部使用

PluginRegistriesBeanDefinitionRegistrar注册器去获取注解的value属性(类型为Plugin接口的Class数组)；然后遍历这个Plugin数组

















，针对每个Plugin在Spring上下文中注册PluginRegistryFactoryBean    
    
    
    
，并设置相应的name和属性     
     
     
     。

如果处理的Plugin有@Qualifier注解 


     


     


     


  ，那么这个要注册的PluginRegistryFactoryBean的name就是@Qualifier注解的value

 




 




 




 
，否则name就是插件名首字母小写+Registry的格式(比如DocumentationPlugin对应构造的bean的name就是

documentationPluginRegistry)   




   




   




   



。

PluginRegistriesBeanDefinitionRegistrar注册器处理过程：

PluginRegistryFactoryBean是一个FactoryBean   

   

   

   

，其内部真正构造的bean的类型是OrderAwarePluginRegistry



 



 



 



。OrderAwarePluginRegistry实例化过程中会调用create静态方法  

     

     

     

 ，传入的plugin集合使用aop代理生成一个ArrayList


  




  




  




  ，这个list中的元素就是Spring上下文中所有的类型为之前遍历的Plugin的bean                   。

PluginRegistryFactoryBean的getObject方法：

这里的targetSource是在PluginRegistryFactoryBean的父类AbstractTypeAwareSupport(实现了InitializingBean接口)中的afterPropertiesSet方法中初始化的(type属性在

PluginRegistriesBeanDefinitionRegistrar注册器中已经设置为遍历的Plugin)：

BeansOfTypeTargetSource的getTarget方法：

举个例子：比如

SpringfoxWebMvcConfiguration中的@EnablePluginRegistries注解里的DocumentationPlugin这个Plugin  


  


  


  


，在处理过程中会找出Spring上下文中所有的Docket(Docket实现了DocumentationPlugin接口)   
     
     
     
，并把该集合设置成name为documentationPluginRegistry


  




  




  




  、类型为OrderAwarePluginRegistry的bean



   




   




   




   ，注册到Spring上下文中    




    




    




    


。

DocumentationPluginsManager类会在之前提到过的配置类中被扫描出来 



 



 



 


，它内部的各个pluginRegistry属性都是@EnablePluginRegistries注解内部构造的各种pluginRegistry实例：

DocumentationPluginsBootstrapper启动类也会在之前提供的配置类中被扫描出来



















。它实现了SmartLifecycle接口                   ，在start方法中




    




    




    




   ，会获取之前初始化的所有documentationPlugins(也就是Spring上下文中的所有Docket)                  。遍历这些Docket并进行scan扫描(使用RequestMappingHandlerMapping的getHandlerMethods方法获取url与方法的所有映射关系

















，然后进行一系列API解析操作)                    ，扫描出来的结果封装成Documentation并添加到DocumentationCache中：

以上就是API解析  


  


  


  


、扫描的大致处理过程



     



     



     



   ，整理如下：

下面分析一下HandlerMapping的处理过程     



     



     



     

。

PropertySourcedRequestMappingHandlerMapping在Swagger2DocumentationConfiguration配置类中被构造：

PropertySourcedRequestMappingHandlerMapping初始化过程中会设置优先级为Ordered.HIGHEST_PRECEDENCE + 1000

















，同时还会根据Swagger2Controller得到RequestMappingInfo映射信息    
    
    
    
，并设置到handlerMethods属性中



















。

PropertySourcedRequestMappingHandlerMapping复写了lookupHandlerMethod方法 


     


     


     


  ，首先会去handlerMethods属性中查询是否存在对应的映射关系

 




 




 




 
，没找到的话使用下一个HandlerMapping进行处理：

Swagger2Controller中只有一个mapping方法   

   

   

   

，默认的path值为/v2/api-docs  

     

     

     

 ，可以通过配置

springfox.documentation.swagger.v2.path 进行修改
    
    
    
  。所以默认情况下 /v2/api-docs?group=person-api   
     
     
     
、/v2/api-docs?group=user-api 这些地址都会被Swagger2Controller所处理     


     


     


     
。

Swagger2Controller内部获取文档信息会去DocumentationCache中查找：

引入springfox带来的影响

影响主要有2点：

应用启动速度变慢


  




  




  




  ，因为额外加载了springfox中的信息  


  


  


  


，同时内存中也缓存了这些API信息

多了一个HandlerMapping   
     
     
     
，并且优先级高 




 




 




 




。以下是springboot应用DispatcherServlet的HandlerMapping集合

   

   

   

 。其中springfox构造的

PropertySourcedRequestMappingHandlerMapping优先级最高     

     

     

     。优先级最高说明第一次查询映射关系都是走PropertySourcedRequestMappingHandlerMapping



   




   




   




   ，而程序中大部分请求都是在RequestMappingHandlerMapping中处理的

优先级问题可以使用BeanPostProcessor处理 



 



 



 


，修改优先级：

SpringBoot项目配置 swagger

@EnableSwagger2@Configurationpublic class Swagger2Config { @Bean public Docket createRestApi() { return new Docket(DocumentationType.SWAGGER_2) .apiInfo(apiInfo()) .select() //为当前包路径 .apis(RequestHandlerSelectors.any()) .paths(PathSelectors.any()) .build(); } //构建 api文档的详细信息函数 private ApiInfo apiInfo() { return new ApiInfoBuilder() //页面标题 .title("功能测试") //创建人 .contact(new Contact("Edison", "xxx@qq.com", "xxx@qq.com")) //版本号 .version("1.0") //描述 .description("API 描述") .build(); }

maven.xml

<!--swagger2--><dependency> <groupId>io.springfox</groupId> <artifactId>springfox-swagger2</artifactId> <version>2.6.1</version> </dependency> <dependency> <groupId>io.springfox</groupId> <artifactId>springfox-swagger-ui</artifactId> <version>2.6.1</version> </dependency>

 ————没有与生俱来的天赋                   ，都是后天的努力拼搏（我是小杨




    




    




    




   ，谢谢你的关注和支持）