本文來自網(wǎng)易云社區(qū)

作者：李哲

二、Swagger-springmvc原理解析

上面介紹了如何將springmvc和springboot與swagger結(jié)合，通過簡單配置生成接口文檔，以及介紹了swagger提供的一些注解。下面將介紹swagger是如何做到與springmvc結(jié)合，自動生成接口文檔。

項(xiàng)目添加完成maven依賴后會加入swagger的依賴包，其中包括swagger- springmvc，swagger-annotations，swagger-models幾個(gè)依賴包。如下圖所示：

其中，swagger-annotations是swagger提供給spring的注解包，上面說的注解基本都在這個(gè)包里面；swagger-models是swagger自己的model類，主要用于將注解解析成后面需要使用的model和一些model數(shù)據(jù)的處理。Swagger-springmvc是swagger接入spring的一個(gè)最重要的包，通過這個(gè)包的處理可以將添加的注解信息解析出來，自動生成接口需要的數(shù)據(jù)，最后通過url請求就能返回接口的信息，通過前端處理就可以在頁面上看到接口的信息。下面將重點(diǎn)分析swagger-springmvc包下的文件，本文中分析的是1.0.2版本的swagger-springmvc，其他版本會存在差異，請自行研究。

下圖是swagger-springmvc包結(jié)構(gòu)，圖中標(biāo)紅的兩個(gè)類是swagger的入口類，根據(jù)包的名字大致能猜出各個(gè)模塊的功能。這里先簡單介紹下，annotation包下只有一個(gè)注解類ApiIgnore，用于忽略不被swagger處理；authorization包下主要用于處理需要認(rèn)證的接口，添加認(rèn)證信息；configuration主要處理配置相關(guān)的操作，其中包含了程序的配置SpringSwaggerConfig類，該類是swagger的默認(rèn)配置類，也可以自己編寫封裝去修改配置（一般都會編寫自己的配置類，設(shè)置一些api信息等）。Controller用于處理請求swagger文檔時(shí)返回?cái)?shù)據(jù)給前端ui；core是整個(gè)處理過程的核心模塊，例如注解的解析，model的處理，一些處理過程中的策略等等；ordering包中是用于處理頁面顯示接口時(shí)，一些排序問題，其中的class都繼承了Ordering<T>類，實(shí)現(xiàn)了Comparator<T>接口；paths包下了類主要是處理前端訪問swagger接口時(shí)的路徑問題；plugin是swagger和spring結(jié)合的適配處理，也是程序的入口，相對spring來說，swagger就像一個(gè)插件接入spring中；scanners和readers兩個(gè)包主要是處理注解的獲取和掃描解析。swagger- springmvc包下的大致結(jié)構(gòu)就是這樣的，看到這是不是覺得swagger沒那么神奇了，其實(shí)swagger做的兩件最主要的事就是：掃描解析注解變成相應(yīng)的model，前端請求接口文檔時(shí)返回后臺處理好的接口信息。

馬上就要進(jìn)入程序入口了，是不是有點(diǎn)激動呢？可能有的人會問，怎么知道Swagger PluginAdapter是程序的入口？配置的文件不是SpringSwaggerConfig嗎？進(jìn)入源代碼就能找到答案，下面來看下SwaggerPluginAdapter類：

這個(gè)類實(shí)現(xiàn)了ApplicationListener<ContextRefreshedEvent>接口，這是一個(gè)spring的接口，在spring的applicationcontext初始化完成后會執(zhí)行onApplicationEvent方法，所以當(dāng)spring啟動后，swagger就會被啟動。而SpringSwaggerConfig中使用了注解@configuration，會在spring啟動時(shí)進(jìn)行swagger配置，在配置的時(shí)候會根據(jù)用戶自定義的配置進(jìn)行設(shè)置，如果用戶沒有定義將用默認(rèn)的配置。下面看下方法onApplicationEvent中的處理，如下圖所示，程序會先去判斷plugins是否存在，不存在直接使用默認(rèn)的，如果配置中設(shè)置了plugin則使用配置中的SwaggerSpringMvcPlugin，最后都調(diào)用Swagger SpringMvcPlugin類的initialize方法。

SwaggerSpringMvcPlugin是swagger和spring框架核心的類。有好多可配置的屬性，并且提供了相應(yīng)的get與set方法。 在該類中，初始化了SwaggerApiResourceListing類（用于掃描RequestMappingHandler方法）的屬性。 當(dāng)調(diào)用initialize()方法的時(shí)候，調(diào)用的則是SwaggerApiResourceListing類的initialize()方法。

在initialize方法中主要做了兩件重要的事，第一通過apiListingReferenceScanner掃描所有的spring請求路徑（RequestMapping），過濾沒在配置類中設(shè)置的include Patterns，將掃描結(jié)果轉(zhuǎn)換為swagger自定義的model中。第二通過apiListingScanner類掃描第一步處理的每一個(gè)請求路徑，根據(jù)swagger的注解掃描每一個(gè)路徑對應(yīng)的接口信息，最后將信息轉(zhuǎn)換為swagger中model并保存在swaggerCache中方便以后使用。

接下來分析具體的掃描過程，ApiListingReferenceScanner中的scan方法是調(diào)用該類中的scanSpringRequestMappings方法。在該方法中主要做的是根據(jù)spring中的Request MappingHandlerMapping找出符合條件的路徑并找出一些需要的信息保存起來。

ApiListingScanner類中主要掃描每個(gè)請求路徑的具體接口信息，具體的掃描過程是通過命令模式執(zhí)行。代碼中的每一種reader對應(yīng)一種具體要執(zhí)行的命令操作，對所有的請求路徑（RequestMapping）分別獲取MediaType、接口描述、接口model等信息。其中，MediaTypeReader是解析請求的MediaType類型，ApiDescriptionReader是解析接口的信息，ApiModelReader是解析接口的model（即ApiModel標(biāo)注的類）。解析完成后分別將這些信息保存起來。ApiDescriptionReader中主要處理了請求路徑，然后通過ApiOperationReader去處理真正的接口信息。execute方法中可以看到分別去處理寫在接口上的注解。

下面以一個(gè)OperationImplicitParametersReader為例介紹各種Reader是如何通過命令模式去處理對應(yīng)的注解，其中通過AnnotationUtils.findAnnotation方法去查詢Api ImplicitParams注解去獲取接口上標(biāo)注的參數(shù)信息，然后在繼承類SwaggerParameterReader中的execute方法中被調(diào)用。

?

其他的注解也是通過這種方式被讀取出來，最后會將這些信息保存到SwaggerCache中，到此swagger處理代碼中的注解就已完成，當(dāng)然過程中還有處理一些其他信息，例如，需要登錄認(rèn)證的信息，處理接口的請求路徑以方便swagger本身請求接口時(shí)應(yīng)用等等。但是這些處理好的信息是怎么能在前端頁面顯示的呢？接下來就研究下swagger如何在前端顯示接口信息。在swagger的默認(rèn)配置類中有個(gè)ComponentScan注解標(biāo)注需要掃描的包c(diǎn)om.mangofactory.swagger.controllers，在該包下有一個(gè)controller叫DefaultSwaggerController，代碼如下：

可以看到，swagger根據(jù)處理好的路徑對應(yīng)返回相應(yīng)的接口信息，從這里可以看到為什么解析的數(shù)據(jù)都放到SwaggerCache中，這樣后臺controller就可以返回請求的接口數(shù)據(jù)，通過前端頁面的解析就能在前端顯示接口的信息。下圖是前端代碼結(jié)構(gòu)，通過index.html訪問接口信息。

至此swagger-springmvc是如何做到通過簡單注解配置就能實(shí)現(xiàn)自動生成接口文檔信息的原理就講完了，具體細(xì)節(jié)處理有興趣者可以自己研究。現(xiàn)在看來swagger也沒這么神奇了，但是其中用到的方法是值得我們學(xué)習(xí)使用的。例如，如何通過spring的方式獲取spring中管理的一些資源，命令模式，結(jié)合spring的插件開發(fā)等等。

三、Swagger其他功能

除了上面介紹的功能外，swagger還有一些其他功能，打開swagger的官網(wǎng)

https://swagger.io/可以看到除了介紹的功能，還有一些其他工具。

這里簡單介紹下swagger包含的其他功能，SwaggerEditor是一個(gè)swagger文檔編輯工具，通過該工具可以實(shí)現(xiàn)靜態(tài)接口文檔編寫，而且可以查看實(shí)時(shí)接口信息，上面一排按鈕可以實(shí)現(xiàn)保存，生成相關(guān)代碼等功能。如下圖所示：

SwaggerCodeGen是一個(gè)代碼生成的工具，即通過該工具可以實(shí)現(xiàn)根據(jù)接口信息生成各種語言的接口代碼，可以生產(chǎn)前端、后臺、移動端代碼框架，可以通過?swagger- codegen-cli腳手架工具或者訪問github地址：https://github.com/swagger-api/swagger- codegen根據(jù)提示操作，里面也有示例。生成前端、移動端的代碼根據(jù)各語言通用的框架實(shí)現(xiàn)接口請求，例如android的代碼中使用okhttp請求接口數(shù)據(jù)；同時(shí)可以通過靜態(tài)接口文檔生成服務(wù)器端代碼，這樣會根據(jù)文檔中定義的接口信息和model生成相應(yīng)的model和controller接口。通過SwaggerCodeGen生成的代碼在大型項(xiàng)目中可能不太實(shí)用，因?yàn)槔锩婧芏啻a不符合人們編碼習(xí)慣，但是在快速開發(fā)的小型項(xiàng)目中可以嘗試使用。

Swagger UI是展示接口頁面的前端框架，接口信息就是通過這個(gè)框架顯示出來的，所以不管是靜態(tài)接口文檔還是通過后臺代碼生成的接口信息都可以通過SwaggerUI來顯示。上面介紹的swagger結(jié)合springmvc使用中使用的就是Swagger UI來顯示接口頁面。下圖是swagger官網(wǎng)上的一個(gè)示例：

Swagger Inspector是一個(gè)測試接口工具，類似postman，主要用來測試請求返回情況，可以通過在線Swagger Inspector測試接口，基本測試是免費(fèi)使用的。swagger還提供了一些高級功能，如安全掃描、復(fù)雜功能測試、load測試及監(jiān)控?cái)?shù)據(jù)等，可以根據(jù)需求付費(fèi)使用。如下圖所示，Swagger Inspector也可以保存請求歷史，可以選擇請求生成swagger文檔。

除此之外，swagger還提供了SwaggerHub，這是一個(gè)swagger倉庫，可以將文檔上傳保存，同時(shí)支持團(tuán)隊(duì)協(xié)作，在線編輯，安全線上查閱等功能。Swagger還提供很多開源項(xiàng)目和活躍的社區(qū)，如果遇到問題可以去尋求幫助。

四、總結(jié)

本文主要介紹了swagger的簡介，如何在springmvc和springboot中使用swagger，swagger是如何在springmvc中發(fā)揮神奇功效的以及swagger的其他功能等。但是swagger也存在一些問題，例如需要在后臺代碼中加一些注解，過多的注解造成注解泛濫；接口文檔需要等到后臺接口寫好才能在前端展示，而一般開發(fā)可能需要先定義好接口，然后才開始寫代碼造成的流程混亂；要很深入的了解swagger需要時(shí)間和精力，對于忙業(yè)務(wù)的開發(fā)可能覺得不值得在上面花時(shí)間學(xué)習(xí)。其實(shí)對于這些問題都有很好的辦法解決，相比通過簡單學(xué)習(xí)就能方便的獲得接口信息而且不用反復(fù)更新文檔是很值得的一件事。對于接口文檔需要等后臺開發(fā)完才能展示的問題，可以先通過靜態(tài)的文檔書寫方式先寫文檔，之后再通過后臺接口方式實(shí)現(xiàn)。

通過上面的介紹，我們了解到swagger是一個(gè)功能非常強(qiáng)大的工具，如果能很好地利用這個(gè)工具將很大程度上提高我們的開發(fā)效率。雖然swagger之前也被爆出安全性問題，但這個(gè)問題在后續(xù)版本中得到了修復(fù)，所以趕快學(xué)習(xí)使用這個(gè)神器。由于時(shí)間倉促，如果文中有錯(cuò)誤請諒解。

附（常用注解表）：

相關(guān)閱讀：接口文檔神器Swagger（上篇）

網(wǎng)易云大禮包：https://www.163yun.com/gift

本文來自網(wǎng)易云社區(qū)，經(jīng)作者李哲授權(quán)發(fā)布

?

相關(guān)文章：
【推薦】?用SolrJ操作Solr做搜索（上篇）
【推薦】?【專家坐堂】四種并發(fā)編程模型簡介
【推薦】?視覺設(shè)計(jì)師的進(jìn)化

總結(jié)

以上是生活随笔為你收集整理的接口文档神器Swagger（下篇）的全部內(nèi)容，希望文章能夠幫你解決所遇到的問題。

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