swagger是一個(gè)API框架，號(hào)稱世界上最流行的API工具。它提供了API管理的全套解決方案，比如API在線編輯器，API UI展示界面，代碼生成器等諸多功能。

如果想引入swagger進(jìn)行API管理。目前 springfox 是一個(gè)很好的選擇，它內(nèi)部會(huì)自動(dòng)解析Spring容器中Controller暴露出的接口，并且也提供了一個(gè)界面用于展示或調(diào)用這些API。下圖就是簡(jiǎn)單的一個(gè)使用springfox的API展示界面。

springfox的前身是swagger-springmvc，用于springmvc與swagger的整合。

如若在springboot項(xiàng)目中使用springfox，需要3個(gè)步驟：

1、maven添加springfox依賴

2、啟動(dòng)類加上@EnableSwagger2注解

3、構(gòu)造Docket bean用于展示API

配置完之后進(jìn)入 http://{path}:{port}/swagger-ui.html 即可查看controller中的接口信息，并按照Docket中配置的規(guī)則進(jìn)行展示。

springfox實(shí)現(xiàn)原理

在分析springfox實(shí)現(xiàn)原理之前，首先看下springfox對(duì)文檔Documentation的定義：

文檔Documentation定義得很清晰，主要由groupName(分組名)、basePath(contextPath)、apiListings(API列表集)、resourceListing(資源列表集)等屬性組成。

其中API列表被封裝成ApiListing。ApiListing中又持有ApiDesciption集合引用，每個(gè)ApiDesciption都持有一個(gè)API集合的引用，Operation也就是具體的接口操作，內(nèi)部包含了該接口對(duì)應(yīng)的http方法、produces、consumes、協(xié)議、參數(shù)集、響應(yīng)消息集等諸多元素。

springfox通過spring-plugin的方式將Plugin注冊(cè)到Spring上下文中，然后使用這些plugin進(jìn)行API的掃描工作，這里的掃描工作其實(shí)也就是構(gòu)造Documentation的工作，把掃描出的結(jié)果封裝成Documentation并放入到DocumentationCache內(nèi)存緩存中，之后swagger-ui界面展示的API信息通過Swagger2Controller暴露，Swagger2Controller內(nèi)部直接從DocumentationCache中尋找Documentation。

下圖就是部分Plugin具體構(gòu)造對(duì)應(yīng)的文檔信息：

代碼細(xì)節(jié)方面的分析：

很明顯，入口處在@EnableSwagger2注解上，該注解會(huì)import一個(gè)配置類Swagger2DocumentationConfiguration。

Swagger2DocumentationConfiguration做的事情：

1、構(gòu)造Bean。比如HandlerMapping，HandlerMapping是springmvc中用于處理請(qǐng)求與handler(controller中的方法)之間映射關(guān)系的接口，springboot中默認(rèn)使用的HandlerMapping是RequestMappingHandlerMapping，Swagger2DocumentationConfiguration配置類里構(gòu)造的是PropertySourcedRequestMappingHandlerMapping，該類繼承RequestMappingHandlerMapping。

2、import其它配置類，比如SpringfoxWebMvcConfiguration、SwaggerCommonConfiguration

3、掃描指定包下的類，并注冊(cè)到Spring上下文中

SpringfoxWebMvcConfiguration配置類做的事情跟Swagger2DocumentationConfiguration類似，不過多了一步構(gòu)造PluginRegistry過程。該過程使用@EnablePluginRegistries注解實(shí)現(xiàn)：

@EnablePluginRegistries注解是spring-plugin模塊提供的一個(gè)基于Plugin類型注冊(cè)PluginRegistry實(shí)例到Spring上下文的注解。

@EnablePluginRegistries注解內(nèi)部使用PluginRegistriesBeanDefinitionRegistrar注冊(cè)器去獲取注解的value屬性(類型為Plugin接口的Class數(shù)組)；然后遍歷這個(gè)Plugin數(shù)組，針對(duì)每個(gè)Plugin在Spring上下文中注冊(cè)PluginRegistryFactoryBean，并設(shè)置相應(yīng)的name和屬性。

如果處理的Plugin有@Qualifier注解，那么這個(gè)要注冊(cè)的PluginRegistryFactoryBean的name就是@Qualifier注解的value，否則name就是插件名首字母小寫+Registry的格式(比如DocumentationPlugin對(duì)應(yīng)構(gòu)造的bean的name就是documentationPluginRegistry)。

PluginRegistriesBeanDefinitionRegistrar注冊(cè)器處理過程：

PluginRegistryFactoryBean是一個(gè)FactoryBean，其內(nèi)部真正構(gòu)造的bean的類型是OrderAwarePluginRegistry。OrderAwarePluginRegistry實(shí)例化過程中會(huì)調(diào)用create靜態(tài)方法，傳入的plugin集合使用aop代理生成一個(gè)ArrayList，這個(gè)list中的元素就是Spring上下文中所有的類型為之前遍歷的Plugin的bean。

PluginRegistryFactoryBean的getObject方法：

這里的targetSource是在PluginRegistryFactoryBean的父類AbstractTypeAwareSupport(實(shí)現(xiàn)了InitializingBean接口)中的afterPropertiesSet方法中初始化的(type屬性在PluginRegistriesBeanDefinitionRegistrar注冊(cè)器中已經(jīng)設(shè)置為遍歷的Plugin)：

BeansOfTypeTargetSource的getTarget方法：

舉個(gè)例子：比如SpringfoxWebMvcConfiguration中的@EnablePluginRegistries注解里的DocumentationPlugin這個(gè)Plugin，在處理過程中會(huì)找出Spring上下文中所有的Docket(Docket實(shí)現(xiàn)了DocumentationPlugin接口)，并把該集合設(shè)置成name為documentationPluginRegistry、類型為OrderAwarePluginRegistry的bean，注冊(cè)到Spring上下文中。

DocumentationPluginsManager類會(huì)在之前提到過的配置類中被掃描出來，它內(nèi)部的各個(gè)pluginRegistry屬性都是@EnablePluginRegistries注解內(nèi)部構(gòu)造的各種pluginRegistry實(shí)例：

DocumentationPluginsBootstrapper啟動(dòng)類也會(huì)在之前提供的配置類中被掃描出來。它實(shí)現(xiàn)了SmartLifecycle接口，在start方法中，會(huì)獲取之前初始化的所有documentationPlugins(也就是Spring上下文中的所有Docket)。遍歷這些Docket并進(jìn)行scan掃描(使用RequestMappingHandlerMapping的getHandlerMethods方法獲取url與方法的所有映射關(guān)系，然后進(jìn)行一系列API解析操作)，掃描出來的結(jié)果封裝成Documentation并添加到DocumentationCache中：

以上就是API解析、掃描的大致處理過程，整理如下：

下面分析一下HandlerMapping的處理過程。

PropertySourcedRequestMappingHandlerMapping在Swagger2DocumentationConfiguration配置類中被構(gòu)造：

PropertySourcedRequestMappingHandlerMapping初始化過程中會(huì)設(shè)置優(yōu)先級(jí)為Ordered.HIGHEST_PRECEDENCE + 1000，同時(shí)還會(huì)根據(jù)Swagger2Controller得到RequestMappingInfo映射信息，并設(shè)置到handlerMethods屬性中。

PropertySourcedRequestMappingHandlerMapping復(fù)寫了lookupHandlerMethod方法，首先會(huì)去handlerMethods屬性中查詢是否存在對(duì)應(yīng)的映射關(guān)系，沒找到的話使用下一個(gè)HandlerMapping進(jìn)行處理：

Swagger2Controller中只有一個(gè)mapping方法，默認(rèn)的path值為/v2/api-docs，可以通過配置 springfox.documentation.swagger.v2.path 進(jìn)行修改。所以默認(rèn)情況下 /v2/api-docs?group=person-api、/v2/api-docs?group=user-api 這些地址都會(huì)被Swagger2Controller所處理。

Swagger2Controller內(nèi)部獲取文檔信息會(huì)去DocumentationCache中查找：

引入springfox帶來的影響

影響主要有2點(diǎn)：

應(yīng)用啟動(dòng)速度變慢，因?yàn)轭~外加載了springfox中的信息，同時(shí)內(nèi)存中也緩存了這些API信息

多了一個(gè)HandlerMapping，并且優(yōu)先級(jí)高。以下是springboot應(yīng)用DispatcherServlet的HandlerMapping集合。其中springfox構(gòu)造的PropertySourcedRequestMappingHandlerMapping優(yōu)先級(jí)最高。優(yōu)先級(jí)最高說明第一次查詢映射關(guān)系都是走PropertySourcedRequestMappingHandlerMapping，而程序中大部分請(qǐng)求都是在RequestMappingHandlerMapping中處理的

優(yōu)先級(jí)問題可以使用BeanPostProcessor處理，修改優(yōu)先級(jí)：

本文作者：中間件小哥

閱讀原文

本文為云棲社區(qū)原創(chuàng)內(nèi)容，未經(jīng)允許不得轉(zhuǎn)載。

總結(jié)

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

如果覺得生活随笔網(wǎng)站內(nèi)容還不錯(cuò)，歡迎將生活随笔推薦給好友。