API管理-舍弃springfox-swagger-ui，采用功能更加丰富的swagger-bootstrap-ui

1. 为什么要使用swagger-bootstrap-ui？

上一篇博客（API管理-基于SpringBoot项目集成swagger实现接口文档自动生成）中我已经提到过使用springfox-swagger-ui的部分问题，上下结构的接口层次不利于接口的查看、无法支持离线下载成pdf或word或html等，而swagger-bootstrap-ui的出现把这些问题都解决了并且还扩展了部分实用新功能，比如：新增接口页面权限功能..

swagger-bootstrap-ui 对比springfox-swagger-ui原生ui有哪些优点：
1. 支持接口pdf和word和markdwon方式对接口文档进行导出，wagger-bootstrap-ui 提供markdwon格式类型的离线文档,开发者可拷贝该内容通过其他markdown转换工具进行转换为html或pdf.
2. 一个项目同时支持swagger-bootstrap-ui、springfox-swagger-ui二种方式同时使用
3. 界面相比springfox-swagger-ui更友好、左右排版结构更加清晰
4. 支持search相关接口内容
5. 可进行接口版本的管理
6. 国际化
7. 支持自定义文档
8. 支持开启生产环境,屏蔽Swagger所有资源接口
9. 可设置在线接口文档权限控制
......

2. 使用方式

基于上一篇博客的基础上新增如下配置：

• 新增swagger-bootstrap-ui 增强ui pom依赖

<!-- swagger-bootstrap-ui增强ui  -->
<dependency>
  <groupId>com.github.xiaoymin</groupId>
  <artifactId>swagger-bootstrap-ui</artifactId>
  <version>1.9.4</version>
</dependency>

• 在MvcConfig类中新增 registry.addResourceHandler("doc.html").addResourceLocations("classpath:/META-INF/resources/");

public void addResourceHandlers(ResourceHandlerRegistry registry) {
   //如果静态文件放到了classpath 下，就如下配置。
   registry.addResourceHandler("/static/**").addResourceLocations("classpath:/static/");

   /*放行swagger*/
   registry.addResourceHandler("swagger-ui.html")
		   .addResourceLocations("classpath:/META-INF/resources/");
   registry.addResourceHandler("doc.html").addResourceLocations("classpath:/META-INF/resources/");
   registry.addResourceHandler("/webjars/**")
		   .addResourceLocations("classpath:/META-INF/resources/webjars/");
   super.addResourceHandlers(registry);
}

• 启动项目、访问地址、查看接口信息：http://localhost:8080/doc.html
• 效果图

3. 如果将markdown(.md)文件快速导出成html或word文件

swagger-bootstrap-ui 提供markdwon格式类型的离线文档,开发者可拷贝该内容通过其他markdown转换工具进行转换为html或pdf.
pandoc安装参考博客：https://blog.csdn.net/xc_zhou/article/details/81009893 , https://www.jianshu.com/p/52cbee87a45a
pandoc下载地址：https://github.com/jgm/pandoc/releases/tag/2.2

1》按照md->HTML->PDF的路径转。于是先把md转为HTML，HTML的样式倒是挺美观，然后在浏览器中使用浏览器的打印功能把HTML转为PDF。
2》md->docx->PDF（推荐）

pandoc -s test.md -o test.docx
pandoc -f markdown -t html -o test.html readme.md

html生成后可以自定样式文件，使文档更好看

4. 总结

swagger-bootstrap-ui 对比springfox-swagger-ui原生ui，比原生ui强大很多，配置使用方式二者一致，swagger扫描到的数据信息是不变的，相当于换了一个管理端页面，呈现出不一样的管理方式，更加友好，推荐使用swagger-bootstrap-ui，详细的功能请参考码云开源项目：swagger-bootstrap-ui。

API管理工具Swagger介绍及Springfox原理分析

swagger是一个API框架，号称世界上最流行的API工具。它提供了API管理的全套解决方案，比如API在线编辑器，API UI展示界面，代码生成器等诸多功能。

如果想引入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处理，修改优先级：

本文作者：中间件小哥
阅读原文
本文为云栖社区原创内容，未经允许不得转载。

java REST API 文档自动生成 —— springfox-swagger

springfox-swagger有什么用？

• 自动生成restAPI文档
• 文档在线查看／在线调试
• 随着代码自动更新
• 自动生成客户端代码
• 自动生成server模拟代码
  
  

openAPI-specification/swagger/springfox

openAPI-specification 是一套描述REST API的规范

swagger 是实现openAPI-specification的一套工具。是个具体实现

springfox 原名swagger-springmvc 是对swagger的java spring的集成。 目前也可以兼容swagger之外的规范，例如RAML和jsonapi。

swagger 1和 swagger 2的区别

swagger1 指的是 OpenAPI Spec用的是1.2版本

swagger2 指的是 OpenAPI Spec用的是2.0版本

springfox-swagger2 对应的 swagger-core 版本是 1.5.3- 1.5.4

• Prerequisites

  You need the following installed and available in your $PATH:

  • Java 7 (http://java.oracle.com)
  • Apache maven 3.0.4 or greater (http://maven.apache.org/)

• Prerequisites 2.X

  You need the following installed and available in your $PATH:

  • Java 8 (http://java.oracle.com)
  • Apache maven 3.0.4 or greater (http://maven.apache.org/)

springfox 架构

                                                                                                                               
                                   +------------------+                                                                 
                                   |                  |        Contains the internal service and                        
                                   |  springfox-core  |        schema description models along with                     
                                   |                  |        their builders.                                          
                                   +---------+--------+                                                                 
                                             ^                                                                          
                                   +---------+--------+                                                                 
                                   |                  |        Contains the service provider interfaces that            
                                   |  springfox-spi   |        can be used to extend and enrich the service models.     
                                   |                  |        For e.g. swagger specific annotation processors.         
                                   +---+------+----+--+                                                                 
                                       ^      ^    ^                                                                    
                       +---------------+----+ | +--+------------------+                                                 
Schema inference       |                    | | |                     | spring web specific extensions that can build
extensions that help   |  springfox-schema  | | |springfox-spring-web | the service models based on RequestMapping   
build up the schema for|                    | | |                     | information. This is the heart library that  
the parameters, models +--------------------+ | +---------------------+ infers the service model.                    
and responses                                 |                                                                         
                                 +------------+-------------+                                                           
                                 |                          |   Common swagger specific extensions                      
                                 | springfox-swagger-common |   that are aware of the different                         
                                 |                          |   swagger annotations.                                    
                                 +-----+---------------+----+                                                           
                                       ^               ^                                                                
                         +-------------+----+     +----+--------------+                                                 
                         |                  |     |                   |  Configurations, and mapping layer              
                         |springfox-swagger1|     |springfox-swagger2 |  that know how to convert the                   
                         |                  |     |                   |  service models to swagger 1.2 and              
                         +------------------+     +-------------------+  swagger 2.0 specification documents.  A
                                                                         Also contains the controller for each
                                                                         of the specific formats.
    

springfox-swagger2

1. 引入jar包

   <dependency>
       <groupId>io.springfox</groupId>
       <artifactId>springfox-swagger2</artifactId>
       <version>2.x.x</version>
   </dependency>
   <dependency>
       <groupId>io.springfox</groupId>
       <artifactId>springfox-swagger-ui</artifactId>
       <version>2.x.x</version>
   </dependency>

2. 全局配置boot

   @SpringBootApplication
   @EnableSwagger2
   public class Application  {
       public static void main(String[] args) {
           SpringApplication.run(Application.class, args);
       }
       
       @Bean
       public Docket testApi() {
           ApiInfo apiInfo = new ApiInfoBuilder()
                   .title("API接口")
                   .description("api")
                   .build();
           return new Docket(DocumentationType.SWAGGER_2)
                   .groupName("default")
                   .genericModelSubstitutes(DeferredResult.class)
                   .useDefaultResponseMessages(false)
                   .forCodeGeneration(true)
                   .pathMapping("/")
                   .select()
                   .build()
                   .apiInfo(apiInfo);
       }
   }

3. 全局配置非boot

   @Configuration
   @EnableWebMvc
   @EnableSwagger2
   public class Application  {
       public static void main(String[] args) {
           SpringApplication.run(Application.class, args);
       }
       
       @Bean
       public Docket testApi() {
           ApiInfo apiInfo = new ApiInfoBuilder()
                   .title("API接口")
                   .description("api")
                   .build();
           return new Docket(DocumentationType.SWAGGER_2)
                   .groupName("default")
                   .genericModelSubstitutes(DeferredResult.class)
                   .useDefaultResponseMessages(false)
                   .forCodeGeneration(true)
                   .pathMapping("/")
                   .select()
                   .build()
                   .apiInfo(apiInfo);
       }
   }

4. 配置controller

   @Api(tags = {"测试组"})
   @RestController
   public class Controller {
   
       @ApiOperation(value = "方法1", notes = "方法1描述")
       @RequestMapping(value = "/CH070", method = {RequestMethod.POST}
           , produces = {"application/json","application/xml"})
       public Response method1(@ApiParam(required = true, value = "参数1")
            @RequestParam(value = "method11") String method2
           , @ApiParam(required = true, value = "method2") 
            @RequestParam(value = "method2", required = true) String method2) {
       }
   
   }
   

5. 集成 spring-data-rest / bean-validators

   <dependency>
       <groupId>io.springfox</groupId>
       <artifactId>springfox-bean-validators</artifactId>
       <version>${springfox.version}</version>
   </dependency>
   <dependency>
       <groupId>io.springfox</groupId>
       <artifactId>springfox-data-rest</artifactId>
       <version>${springfox.version}</version>
    <dependency>

   @Import({SpringDataRestConfiguration.class, BeanValidatorPluginsConfiguration.class})

springfox-swagger-ui

swagger-ui 是一个node工程，通过swagger暴露的接口，展示文档信息

springfox-swagger-ui 是一个webjar, 方便进行maven集成

springfox-ui 目录结构：

```
META-INF
    |- resources
        |- webjars
            |-swagger-ui.html
            |-springfox-swagger-ui
                |-css
                |-fonts
                |-images
                |-lang
                |-lib
                |-o2c.html
                |-springfox.js
                |-swagger-ui.min.js
```

什么是webjar？

• 第三方小工具, 把静态资源进行打包，幷版本化管理。

• spring-boot 默认支持。

  //WebMvcAutoConfiguration#addResourceHandlers
  if (!registry.hasMappingForPattern("/webjars/**")) {
      customizeResourceHandlerRegistration(
              registry.addResourceHandler("/webjars/**")
                      .addResourceLocations(
                              "classpath:/META-INF/resources/webjars/")
              .setCachePeriod(cachePeriod));
  }

• 非spring-boot

  <mvc:resources mapping="/swagger-ui.html" location="classpath:/META-INF/resources/"/>
  <mvc:resources mapping="/webjars/**" location="classpath:/META-INF/resources/webjars/"/>
  

其他风格的替代品：

• swagger-ui-layer
• Swagger-Bootstrap-UI
  
  

swagger-codegen

swagger-codegen这个是总入口。不过文档比较乱，不太好找，下面列出几个关键点

从哪里获得输入的配置文件？

• springfox-swagger-ui 默认输出地址为/v2/api-docs?group=default。
  group可以自定义，default group可以不传。 通过浏览器地址栏请求可能无法接受json格式的返回报文，这时可以通过更改spring-boot配置项springfox.documentation.swagger.v2.path 添加后缀解决，例如：/v2/api-docs.json

  #springfox.documentation.swagger2.web.Swagger2Controller
  public static final String DEFAULT_URL = "/v2/api-docs";
      
  @RequestMapping(
      value = DEFAULT_URL,
      method = RequestMethod.GET,
      produces = { APPLICATION_JSON_VALUE, HAL_MEDIA_TYPE })
  @PropertySourcedMapping(
      value = "${springfox.documentation.swagger.v2.path}",
      propertyKey = "springfox.documentation.swagger.v2.path")
  @ResponseBody
  public ResponseEntity<Json> getDocumentation(
       @RequestParam(value = "group", required = false) String swaggerGroup,
      HttpServletRequest servletRequest) {

• 在线生成 https://generator.swagger.io/ 貌似需要把配置文件暴露到外网

• swagger-codegen-maven-plugin maven 自动化集成

• 具体有哪些配置项 源码 文档没怎么说，源码里有列表。。

• 模拟Server Server stub generator HOWTO 包括spring-boot和Spring MVC

Spring boot + io.springfox Swagger2 统一添加header 参数的方法:globalOperationParameters

在百度上面找了好久也没找到一个满意的答案

在所有rest统一添加一个参数应该属于一个通用的解决办法,比如统一添加basic验证,或者token,apiKey

使用如下代码可以在swagger-ui上面自动显示需要添加的header参数

但是会对所有的rest添加,如果想只在部分添加,login这样的不需要添加怎么办呢?暂时没找到办法

如果你有办法请写在评论里,供后面的人来用,如果我发现办法了,也会写在评论里

package com.XXXX.config;

import java.util.ArrayList;
import java.util.List;

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;

import springfox.documentation.builders.ParameterBuilder;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.schema.ModelRef;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.service.Parameter;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

@Configuration
@EnableSwagger2
public class SwaggerConfig
{
  
  @Bean
  public Docket petApi()
  {

//可以添加多个header或参数
    ParameterBuilder aParameterBuilder = new ParameterBuilder();
    aParameterBuilder.name("Authorization").description("i").modelRef(new ModelRef("string")).parameterType("header").required(false).build();
    ParameterBuilder aParameterBuilder1 = new ParameterBuilder();
    aParameterBuilder1.name("token").description("").modelRef(new ModelRef("string")).parameterType("query").required(false).build();
    List<Parameter> aParameters = new ArrayList<Parameter>();
    aParameters.add(aParameterBuilder.build());
    aParameters.add(aParameterBuilder1.build());
    return new Docket(DocumentationType.SWAGGER_2).apiInfo(getApiInfo()).useDefaultResponseMessages(false).globalOperationParameters(aParameters);
  }
  
  private ApiInfo getApiInfo()
  {
    ApiInfo ai = new ApiInfo("XXXXX", "XXXXXX", null, null, null, null, null);
    return ai;
  }
  
}
 

关于Springfox 3 依赖与 swagger 注释 2 jars和spring依赖注入的三种方式 注解的介绍现已完结，谢谢您的耐心阅读，如果想了解更多关于API管理-舍弃springfox-swagger-ui，采用功能更加丰富的swagger-bootstrap-ui、API管理工具Swagger介绍及Springfox原理分析、java REST API 文档自动生成 —— springfox-swagger、Spring boot + io.springfox Swagger2 统一添加header 参数的方法:globalOperationParameters的相关知识，请在本站寻找。