swagger原理简介

swagger简介
swagger确实是个好东西，能够跟据业务代码自动生成相关的api接口文档，尤为用于restful风格中的项目，开发人员几乎能够不用专门去维护rest api，这个框架能够自动为你的业务代码生成restfut风格的api，并且还提供相应的测试界面，自动显示json格式的响应。大大方便了后台开发人员与前端的沟通与联调成本。

springfox-swagger简介
签于swagger的强大功能，Java开源界大牛spring框架迅速跟上，它充分利用自已的优点，把swagger集成到本身的项目里，整了一个spring-swagger，后来便演变成springfox。springfox自己只是利用自身的aop的特色，经过plug的方式把swagger集成了进来，它自己对业务api的生成，仍是依靠swagger来实现。

关于这个框架的文档，网上的资料比较少，大部分是入门级的简单使用。本人在集成这个框架到本身项目的过程当中，遇到了很多坑，为了解决这些坑，我不得不扒开它的源码来看个究竟。此文，就是记述本人在使用springfox过程当中对springfox的一些理解以及须要注意的地方。

springfox大体原理
springfox的大体原理就是，在项目启动的过种中，spring上下文在初始化的过程，框架自动跟据配置加载一些swagger相关的bean到当前的上下文中，并自动扫描系统中可能须要生成api文档那些类，并生成相应的信息缓存起来。若是项目MVC控制层用的是springMvc那么会自动扫描全部Controller类，跟据这些Controller类中的方法生成相应的api文档。

因本人的项目就是SpringMvc，因此此文就以SpringMvc集成springfox为例来讨论springfox的使用与原理。

SpringMvc集成springfox的步骤

首先，项目须要加入如下三个依赖：

<!– sring mvc依赖 –>
<dependency>
   <groupId>org.springframework</groupId>
   <artifactId>spring-webmvc</artifactId>
   <version>4.2.8.RELEASE</version>
</dependency>

<!– swagger2核心依赖 –>
<dependency>
   <groupId>io.springfox</groupId>
   <artifactId>springfox-swagger2</artifactId>
   <version>2.6.1</version>
</dependency>

<!– swagger-ui为项目提供api展现及测试的界面 –>
<dependency>
   <groupId>io.springfox</groupId>
   <artifactId>springfox-swagger-ui</artifactId>
   <version>2.6.1</version>
</dependency>

上面三个依赖是项目集成springmvc及springfox最基本的依赖，其它的依赖这里省略。其中第一个是springmvc的基本依赖，第二个是swagger依赖，第三个是界面相关的依赖，这个不是必须的，若是你不想用springfox自带的api界面的话，也能够不用这个，而另外本身写一套适合本身项目的界面。加入这几个依赖后，系统后会自动加入一些跟springfox及swagger相关jar包，我粗略看了一下，主要有如下这么几个：

springfox-swagger2-2.6.1.jar
swagger-annotations-1.5.10.jar
swagger-models-1.5.10.jar
springfox-spi-2.6.1.jar
springfox-core-2.6.1.jar
springfox-schema-2.6.1.jar
springfox-swagger-common-2.6.1.jar
springfox-spring-web-2.6.1.jar
guava-17.0.jar
spring-plugin-core-1.2.0.RELEASE.jar
spring-plug-metadata-1.2.0.RELEASE.jar
spring-swagger-ui-2.6.1.jar
jackson-databind-2.2.3.jar
jackson-annotations-2.2.3.jar

上面是我经过目测以为springfox可能须要的jar，可能没有彻底例出springfox所需的全部jar。从上面jar能够看出springfox除了依赖swagger以外，它还须要guava、spring-plug、jackson等依赖包（注意jackson是用于生成json必须的jar包，若是项目里自己没有加入这个依赖，为了集成swagger的话必须额外再加入这个依赖）。

springfox的简单使用
若是只用springfox的默认的配置的话，与springmvc集成起来很是简单，只要写一个相似于如下代码的类放到你的项目里就好了，代码以下：

@Configuration
@EnableWebMvc
@EnableSwagger2
publicclass ApiConfig {

}

注意到，上面是一个空的java类文件，类名能够随意指定，但必须加入上述类中标出的@Configuration、@EnableWebMvc、@EnableSwagger2三个注解，这样就完成了springmvc与springfox的基本集成，有了三个注解，项目启动后就能够直接用相似于如下的地址来查看api列表了：

http://127.0.0.1:8080/jadDemo/swagger-ui.html

这确实是一个很神奇的效果，简单的三个注解，系统就自动显示出项目里全部Controller类的全部api了。如今，咱们就这个配置类入手，简单分析它的原理。这个类中没有任何代码，很显然，三个注解起了相当重要的做用。其中@Configuration注解是spring框架中自己就有的，它是一个被@Component元注解标识的注解，因此有了这个注解后，spring会自动把这个类实例化成一个bean注册到spring上下文中。第二个注解@EnableWebMvc故名思义，就是启用springmvc了，在Eclipse中点到这个注解里面简单看一下，它就是经过元注解@Import(DelegatingWebMvcConfiguration.class)往spring context中塞入了一个DelegatingWebMvcConfiguration类型的bean。我想，这个类的目的应该就是为swagger提供了一些springmvc方面的配置吧。第三个注解：@EnableSwagger2，看名字应该能够想到，是用来集成swagger2的，他经过元注解：@Import({Swagger2DocumentationConfiguration.class})，又引入了一个Swagger2DocumentationConfiguration类型的配置bean，而这个就是Swagger的核心配置了。它里面的代码以下：

@Configuration
@Import({ SpringfoxWebMvcConfiguration.class, SwaggerCommonConfiguration.class })
@ComponentScan(basePackages = {
    "springfox.documentation.swagger2.readers.parameter",
    "springfox.documentation.swagger2.web",
    "springfox.documentation.swagger2.mappers"

})

publicclassSwagger2DocumentationConfiguration {
  @Bean
  public JacksonModuleRegistrar swagger2Module() {

    returnnewSwagger2JacksonModule();
  }
}

这个类头部经过一些注解，再引入SpringfoxWebMvcConfiguration类和SwaggerCommonConfiguration类，并经过ComponentScan注解，自动扫描springfox .swagger2相关的的bean到spring context中。这里，我最感兴趣的是SpringfoxWebMvcConfiguration这个类，这个类我猜应该就是springfox集成mvc比较核心的配置了，点进去，看到如下代`码：

@Configuration
@Import({ModelsConfiguration.class })
@ComponentScan(basePackages = {
 "springfox.documentation.spring.web.scanners",
 "springfox.documentation.spring.web.readers.operation",
 "springfox.documentation.spring.web.plugins",
 "springfox.documentation.spring.web.paths"
})

@EnablePluginRegistries({ 

    DocumentationPlugin.class,
    ApiListingBuilderPlugin.class,
    OperationBuilderPlugin.class,
    ParameterBuilderPlugin.class,
    ExpandedParameterBuilderPlugin.class,
    ResourceGroupingStrategy.class,
    OperationModelsProviderPlugin.class,
    DefaultsProviderPlugin.class,
    PathDecorator.class
})

publicclassSpringfoxWebMvcConfiguration {

}

这个类中下面的代码，无非就是经过@Bean注解再加入一些新的Bean，我对它的兴趣不是很大，我最感兴趣的是头部经过@EnablePluginRegistries加入的那些东西。springfox是基于spring-plug的机制整合swagger的，spring-plug具体是怎么实现的，我暂时尚未时间去研究spring-plug的原理。但在下文会提到本身写一个plug插件来扩展swagger的功能。上面经过@EnablePluginRegistries加入的plug中，尚未时间去看它所有的代码，目前我看过的代码主要有ApiListingBuilderPlugin.class,OperationBuilderPlugin.class,ParameterBuilderPlugin.class, ExpandedParameterBuilderPlugin.class,

　　第一个ApiListingBuilderPlugin，它有两个实现类，分别是ApiListingReader和SwaggerApiListingReader。其中ApiListingReader会自动跟据Controller类型生成api列表，而SwaggerApiListingReader会跟据有@Api注解标识的类生成api列表。OperationBuilderPlugin插件就是用来生成具体api文档的，这个类型的插件，有不少不少实现类，他们各自分工，各作各的事情，具体我没有仔细去看，只关注了其中一个实现类：OperationParameterReader，这个类是用于读取api参数的Plugin。它依赖于ModelAttributeParameterExpander工具类，能够将Controller中接口方法参数中非简单类型的命令对像自动解析它内部的属性得出包含全部属性的参数列表（这里存在一个可能会出现无限递归的坑，下文有介绍）。而ExpandedParameterBuilderPlugin插件，主要是用于扩展接口参数的一些功能，好比判断这个参数的数据类型以及是否为这个接口的必须参数等等。整体上说，整个springfox-swagger内部实际上是由这一系列的plug转运起来的。他们在系统启动时，就被调起来，有些用来扫描出接口列表，有些用来读取接口参数等等。他们共同的目地就是把系统中全部api接口都扫描出来，并缓存起来供用户查看。那么，这一系列表plug究竟是如何被调起来的，它们的执行入口倒底在哪？ 
　　咱们把注意点放到上文SpringfoxWebMvcConfiguration这个类代码头部的ComponentScan注解内容上来，这一段注解中扫描了一个叫springfox.documentation.spring.web.plugins的package，这个package在springfox-spring-web-2.6.1.jar中能够找到。这个package下，咱们发现有两个很是核心的类，那就是DocumentationPluginsManager和DocumentationPluginsBootstrapper。对于第一个DocumentationPluginsManager，它是一个没有实现任何接口的bean，但它内部有诸多PluginRegistry类型的属性，并且都是经过@Autowired注解把属性值注入进来的。接合它的类名来看，很容易想到，这个就是管理全部plug的一个管理器了。很好理解，由于ComponentScan注解的配置，全部的plug实例都会被spring实例化成一个bean，而后被注入到这个DocumentationPluginsManager实例中被统一管理起来。在这个package中的另外一个重要的类DocumentationPluginsBootstrapper，看名字就能够猜到，他可能就是plug的启动类了。点进去看具体时就能够发现，他果真是一个被@Component标识了的组件，并且它的构造方法中注入了刚刚描述的DocumentationPluginsManager实例，并且最关键的，它还实现了SmartLifecycle接口。对spring bean生命周期有所了解的人的都知道，这个组件在被实例化为一个bean归入srping context中被管理起来的时候，会自动调用它的start()方法。点到start()中看代码时就会发现，它有一行代码scanDocumentation(buildContext(each));就是用来扫描api文档的。进一步跟踪这个方法的代码，就能够发现，这个方法最终会经过它的DocumentationPluginsManager属性把全部plug调起一块儿扫描整个系统并生成api文档。扫描的结果，缓存在DocumentationCache这个类的一个map属性中。

　　以上就是，srpingMvc整合springfox的大体原理。它主要是经过EnableSwagger2注解，向spring context注入了一系列bean，并在系统启动的时候自动扫描系统的Controller类，生成相应的api信息并缓存起来。此外，它还注入了一些被@Controller注解标识的Controller类，做为ui模块访问api列表的入口。好比springfox-swagger2-2.6.1.jar包中的Swagger2Controller类。这个Controller就是ui模块中用来访问api列表的界面地址。在访问http://127.0.0.1:8080/jadDemo/swagger-ui.html这个地址查看api列表时，经过浏览器抓包就能够看到，它是经过相似于http://127.0.0.1:8080/jadDemo/v2/api-docs?group=sysGroup这样的地址异步得到api信息（Json格式）并显示到界面上，这个地址后台对应的Controller入口就是上文的Swagger2Controller类，这个类收到请求后，直接从事先初始化好的缓存中的取出api信息生成json字符串返回。

了解了springfox的原理，下面来看看springfox使用过程当中，我遇到的哪些坑。

springfox第一大坑：配置类生成的bean必须与spring mvc共用同一个上下文。

前文描述了，在springmvc项目中，集成springfox是只要在项目写一个以下的没有任何业务代码的简单配置类就能够了。

@Configuration
@EnableWebMvc
@EnableSwagger2
publicclass ApiConfig {

}

由于@Configuration注解的做用，spring会自动把它实例化成一个bean注入到上下文。但切记要注意的一个坑就是：这个bean所在的上下文必须跟spring mvc为同一个上下文。怎么解理呢？由于在实际的spring mvc项目中，一般有两个上下文，一个是跟上下文，另外一个是spring mvc（它是跟上下文的子上下文）。其中跟上下文是就是web.xml文件中跟spring相关的那个org.springframework.web.context.request.RequestContextListener监听器，加载起来的上下文，一般咱们会写一个叫spring-contet.xml的配置文件，这里面的bean最终会初始化到跟上下文中，它主要包括系统里面的service,dao等bean，也包括数据源、事物等等。而另外一个上下文是就是spring mvc了，它经过web.xml中跟spring mvc相关的那个org.springframework.web.servlet.DispatcherServlet加载起来，他一般有一个配置文件叫spring-mvc.xml。咱们在写ApiConfig这个类时，若是决定用@Configuration注解来加载，那么就必须保证这个类所在的路径恰好在springmvc的component-scan的配置的base-package范围内。由于在ApiConfig在被spring加载时，会注入一列系列的bean，而这些bean中，为了能自动扫描出全部Controller类，有些bean须要依赖于SpringMvc中的一些bean，若是项目把Srpingmvc的上下文与跟上下文分开来，做为跟上下文的子上下文的话。若是不当心让这个ApiConfig类型的bean被跟上文加载到，由于root context中没有spring mvc的context中的那些配置类时就会报错。 
　　实事上，我并不同意经过@Configuration注解来配置Swagger，由于我认为，Swagger的api功能对于生产项目来讲是无关紧要的。咱们Swagger每每是用于测试环境供项目前端团队开发或供别的系统做接口集成使上。系统上线后，极可能在生产系统上隐藏这些api列表。 但若是配置是经过@Configuration注解写死在java代码里的话，那么上线的时候想去掉这个功能的时候，那就尴尬了，不得不修改java代码从新编译。基于此，我推荐的一个方法，经过spring最传统的xml文件配置方式。具体作法就是去掉@Configuration注解，而后它写一个相似于<bean class=”com.jad.web.mvc.swagger.conf.ApiConfig"/>这样的bean配置到spring的xml配置文件中。在root context与mvc的context分开的项目中，直接配置到spring-mvc.xml中，这样就保证了它跟springmvc的context必定处于同一个context中。

springfox第二大坑：Controller类的参数，注意防止出现无限递归的状况。

Spring mvc有强大的参数绑定机制，能够自动把请求参数绑定为一个自定义的命令对像。因此，不少开发人员在写Controller时，为了偷懒，直接把一个实体对像做为Controller方法的一个参数。好比下面这个示例代码：

@RequestMapping(value = “update”)
public String update(MenuVo menuVo, Model model){

}

        这是大部分程序员喜欢在Controller中写的修改某个实体的代码。在跟swagger集成的时候，这里有一个大坑。若是MenuVo这个类中全部的属性都是基本类型，那还好，不会出什么问题。但若是这个类里面有一些其它的自定义类型的属性，并且这个属性又直接或间接的存在它自身类型的属性，那就会出问题。例如：假如MenuVo这个类是菜单类，在这个类时又含有MenuVo类型的一个属性parent表明它的父级菜单。这样的话，系统启动时swagger模块就因没法加载这个api而直接报错。报错的缘由就是，在加载这个方法的过程当中会解析这个update方法的参数，发现参数MenuVo不是简单类型，则会自动以递归的方式解释它全部的类属性。这样就很容易陷入无限递归的死循环。 
　　为了解决这个问题，我目前只是本身写了一个OperationParameterReader插件实现类以及它依赖的ModelAttributeParameterExpander工具类，经过配置的方式替换掉到springfox原来的那两个类，偷梁换柱般的把参数解析这个逻辑替换掉，并避开无限递归。固然，这至关因而一种修改源码级别的方式。我目前尚未找到解决这个问题的更完美的方法，因此，只能建议你们在用spring-fox Swagger的时候尽可能避免这种无限递归的状况。毕竟，这不符合springmvc命令对像的规范，springmvc参数的命令对像中最好只含有简单的基本类型属性。

springfox第三大坑：api分组相关，Docket实例不能延迟加载

　　springfox默认会把全部api分红一组，这样经过相似于http://127.0.0.1:8080/jadDemo/swagger-ui.html这样的地址访问时，会在同一个页面里加载全部api列表。这样，若是系统稍大一点，api稍微多一点，页面就会出现假死的状况，因此颇有必要对api进行分组。api分组，是经过在ApiConf这个配置文件中，经过@Bean注解定义一些Docket实例，网上常见的配置以下:

@EnableWebMvc
@EnableSwagger2
publicclass ApiConfig {
@Bean
 public Docket customDocket() {
       return newDocket(DocumentationType.SWAGGER_2).apiInfo(apiInfo());
  }
}

        上述代码中经过@Bean注入一个Docket，这个配置并非必须的，若是没有这个配置，框架会本身生成一个默认的Docket实例。这个Docket实例的做用就是指定全部它能管理的api的公共信息，好比api版本、做者等等基本信息，以及指定只列出哪些api（经过api地址或注解过滤）。

Docket实例能够有多个，好比以下代码：

@EnableWebMvc
@EnableSwagger2
publicclass ApiConfig {
@Bean
 public Docket customDocket1() {

       return newDocket(DocumentationType.SWAGGER_2)
           .groupName(“apiGroup1”).apiInfo(apiInfo()).select()
           .paths(PathSelectors.ant(“/sys/**”));
    }

@Bean
 public Docket customDocket2() {
       return newDocket(DocumentationType.SWAGGER_2)
        .groupName(“apiGroup2”).apiInfo(apiInfo())
        .select()
        .paths(PathSelectors.ant(“/shop/**”));
    }
}

        当在项目中配置了多个Docket实例时，也就能够对api进行分组了，好比上面代码将api分为了两组。在这种状况下，必须给每一组指定一个不一样的名称，好比上面代码中的apiGroup1和apiGroup2，每一组能够用paths经过ant风格的地址表达式来指定哪一组管理哪些api。好比上面配置中，第一组管理地址为/sys/开头的api第二组管理/shop/开头的api。固然，还有不少其它的过滤方式，好比跟据类注解、方法注解、地址正则表达式等等。分组后，在api列表界面右上角的下拉选项中就能够选择不一样的api组。这样就把项目的api列表分散到不一样的页面了。这样，即方便管理，又不致于页面因须要加载太多api而假死。 
　　然而，同使用@Configuration同样，我并不同意使用@Bean来配置Docket实例给api分组。由于这样，一样会把代码写死。因此，我推荐在xml文件中本身配置Docket实例实现这些相似的功能。固然，考虑到Docket中的众多属性，直接配置bean比较麻烦，能够本身为Docket写一个FactoryBean，而后在xml文件中配置FactoryBean就好了。然而将Docket配置到xml中时。又会遇到一个大坑，就那是，spring对bean的加载方式默认是延迟加载的，在xml中直接配置这些Docket实例Bean后。你会发现，没有一点效果，页面左上角的下拉列表中跟本没有你的分组项。

　　这个问题曾困扰过我好几个小时，后来凭经验推测出多是由于sping bean默认延迟加载，这个Docket实例还没加载到spring context中。实事证实，个人猜想是对的。我不知道这算是springfox的一个bug，仍是由于我跟本不应把对Docket的配置从原来的java代码中搬到xml配置文件中来。  　　springfox其它的坑：springfox还有些其它的坑，好比@ApiOperation注解中，若是不指定httpMethod属性具体为某个get或post方法时，api列表中，会它get,post,delete,put等全部方法都列出来，搞到api列表重复的太多，很难看。另外，还有在测试时，遇到登陆权限问题，等等。这一堆堆的比较容易解决的小坑，由于篇幅有限，我就很少说了。还有好比@Api、@ApiOperation及@ApiParam等等注解的用法，网上不少这方面的文档，我就不重复了。