之前用 swagger 都是簡(jiǎn)單的使用,沒有考慮過 swagger 具體的實(shí)現(xiàn),不過這一篇文章也并沒有介紹 swagger 的具體實(shí)現(xiàn),而是從 swagger 的 plugin 切入,研究自定義 swagger plugin 的問題
我們知道 swagger 集成進(jìn) spring 或 spring-boot 是通過@EnableSwagger2或者是在 spring-servlet.xml 中增加一個(gè)bean 的配置(具體這些都可以去網(wǎng)上隨便搜搜都有了),然后通過點(diǎn)擊進(jìn)@EnableSwagger2進(jìn)去可以看見這個(gè)注解的具體實(shí)現(xiàn)過程,這里有一篇博客,介紹的挺詳細(xì)的
http://blog.csdn.net/qq_25615395/article/details/70229139
然后這里介紹一下這篇文章里沒有涉及到的,或者說是沒有展開講的內(nèi)容,關(guān)于plugin 的使用.
swagger 通過@EnableSwagger2這個(gè)注解進(jìn)去(或者 spring-servlet.xml 中添加的 bean),會(huì)到一個(gè) SpringSwaggerConfig 的類中,這個(gè)類是 swagger 的配置類,比較重要的這里面配置了一個(gè) swaggerPluginAdapter的 bean
public class SwaggerPluginAdapter implements ApplicationListener<ContextRefreshedEvent>
這個(gè)bean 實(shí)現(xiàn)了ApplicationListener 這個(gè)接口的onApplicationEvent方法
@Override
public void onApplicationEvent(ContextRefreshedEvent contextRefreshedEvent) {
if (initialized.compareAndSet(false, true)) {
log.info("Context refreshed");
ApplicationContext applicationContext = contextRefreshedEvent.getApplicationContext();
Map<String, SwaggerSpringMvcPlugin> plugins = BeanFactoryUtils.beansOfTypeIncludingAncestors(
applicationContext,
SwaggerSpringMvcPlugin.class);
if (plugins.isEmpty()) {
log.info("Did not find any SwaggerSpringMvcPlugins so creating a default one");
new SwaggerSpringMvcPlugin(springSwaggerConfig)
.build()
.initialize();
} else {
log.info("Found custom SwaggerSpringMvcPlugins");
for (Map.Entry<String, SwaggerSpringMvcPlugin> entry : plugins.entrySet()) {
if (entry.getValue().isEnabled()) {
log.info("initializing plugin bean {}", entry.getKey());
entry.getValue()
.build()
.initialize();
} else {
log.info("Skipping initializing disabled plugin bean {}", entry.getKey());
}
}
}
} else {
log.info("Skipping SwaggerSpringMvcPlugin initialization already initialized!");
}
}
這段代碼的核心大概是在應(yīng)用的上下文中去找,有沒有滿足設(shè)定條件的 plugin,如果沒有,則 swagger 會(huì)自己建一個(gè)默認(rèn)的,這個(gè)默認(rèn)的也就是平時(shí)我們使用的,所以在這里,我們就可以做一些自定義的工作.做這些工作,需要?jiǎng)?chuàng)建一個(gè)繼承SwaggerSpringMvcPlugin的類和一個(gè)自定義的SwaggerConfig 類(這個(gè)類也就是在 spring-servlet.xml 中創(chuàng)建成 bean的那個(gè)類)
首先我們需要?jiǎng)?chuàng)建一個(gè)繼承于SwaggerSpringMvcPlugin的類,并將這個(gè)類注射成應(yīng)用上下文中的bean,在創(chuàng)建這個(gè)bean 的時(shí)候,需要注意的是得要注入SwaggerSpringConfig 這個(gè)類.當(dāng)在應(yīng)用上下文中注入了SwaggerSpringMvcPlugin這個(gè) bean 之后,在上面那段代碼中就可以監(jiān)測(cè)到上下文中有自定義的 plugin,則就會(huì)跑到下面那部分.
所以自定義的 plugin 類需要重寫父類的 build 方法和initialize方法,這兩個(gè)方法中的就是 plugin 類的核心代碼實(shí)現(xiàn)
public SwaggerSpringMvcPlugin build() {
if (initialized.compareAndSet(false, true)) {
configure();
buildSwaggerGlobalSettings();
buildApiListingReferenceScanner();
buildSwaggerApiResourceListing();
}
return this;
}
protected void initialize() {
if (enabled) {
this.build().swaggerApiResourceListing.initialize();
}
}
后面部分的代碼其實(shí)沿著源碼一路點(diǎn)下去,就可以看見具體的實(shí)現(xiàn)過程,這里也大致講一下.有兩個(gè)部分,一個(gè)是 ApiResourceListing,一個(gè)是 ApiListingReferenceScanner,前面是對(duì)使用了@Api 注解的類進(jìn)行掃描,并解析,后面一個(gè)是從前面解析的類中,把使用了@ApiOperation 注解的方法找出來并解析,所以很容易想到,如果需要加入特殊的類掃描注解,可以使用自定義的ApiResourceListing,如果需要加入特殊的方法的注解,就自定義 scanner 就好了.包括swagger 中的各個(gè)注解,都是從 ApiListingReferenceScanner這個(gè)類中引申開來,這里貼一下源碼中關(guān)于這部分的代碼結(jié)構(gòu),感興趣的可以點(diǎn)進(jìn)去一個(gè)一個(gè)的看看,這些也都是可以由用戶自己自定義的
額,不會(huì)貼圖,湊合看吧,都很好找到的...
通過這一些的方法出來之后,會(huì)到ApiResourceListing這個(gè)類中
swaggerCache.addSwaggerResourceListing(swaggerGroup, resourceListing);
的這一句代碼,這里就是將解析好的resourceListing,添加到 swaggerCache 之中去,swaggerGroup 是用戶通過配置文件添加的組名,這個(gè)沒啥,關(guān)鍵是 swaggerCache,我之前也不是很懂這個(gè)到底是干嘛的,不過看源碼的時(shí)候,可以知道resourceListing里面已經(jīng)是把所有帶有注解的類和方法的有用信息都提取出來保存在一個(gè)model 中,所以估計(jì) swaggerCache 應(yīng)該是存放這些信息并在其他地方通過這個(gè) cache 獲取到這些信息并創(chuàng)建我們熟知的 swagger 頁面的,去查了一下大概,差不多也就是這個(gè)意思,這個(gè)就屬于 swagger 實(shí)現(xiàn)原理的后一半部分了,這里也就不贅述了,還是那句話,感興趣可以去 Google 一下,應(yīng)該都有的.
這里主要也就是講一個(gè)思路,所以具體代碼沒有貼,貼的也都是 swagger 自帶的實(shí)現(xiàn),我覺得如果真的要做,還是要自己動(dòng)手嘗試一下的.
