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處理，修改優先級：

本文作者：中間件小哥

閱讀原文

本文為云棲社區原創內容，未經允許不得轉載。

總結

以上是生活随笔為你收集整理的swagger内部类_API管理工具Swagger介绍及Springfox原理分析的全部內容，希望文章能夠幫你解決所遇到的問題。

如果覺得生活随笔網站內容還不錯，歡迎將生活随笔推薦給好友。