Swagger入門教程

前言

swagger 是一款restful接口的文檔線上自動生成+功能測試功能軟體。本文簡單介紹了在項目中內建swagger的方法和一些常見問題。如果想深入分析項目源碼，了解更多内容，見參考資料。

swagger 是一個規範和完整的架構，用于生成、描述、調用和可視化 restful 風格的 web 服務。總體目标是使用戶端和檔案系統作為伺服器以同樣的速度來更新。檔案的方法，參數和模型緊密內建到伺服器端的代碼，允許api來始終保持同步。swagger 讓部署管理和使用功能強大的api從未如此簡單。

一、使用介紹

什麼是 swagger?

swagger™的目标是為rest apis 定義一個标準的，與語言無關的接口，使人和計算機在看不到源碼或者看不到文檔或者不能通過網絡流量檢測的情況下能發現和了解各種服務的功能。當服務通過swagger定義，消費者就能與遠端的服務互動通過少量的實作邏輯。類似于低級程式設計接口，swagger去掉了調用服務時的很多猜測。

浏覽 swagger-spec 去了解更多關于swagger 項目的資訊，包括附加的支援其他語言的庫。

如何內建swagger-springmvc到我們的項目中?

依賴：

maven

gradle

compile "com.mangofactory:swagger-springmvc:0.9.4"

使用：

要最快捷地啟動swagger-springmvc項目并且使用預設設定，推薦的方式是使用swaggerspringmvc插件

spring java configuration

spring xml configuration

swaggerspringmvcplugin xml configuration

為了使用這個插件，你需要創造一個spring java配置類。使用spring的 @configuration ，這個配置類必須被定義到你的xml上下文

swaggerspringmvcplugin spring java configuration

使用@enableswagger注解

自動注入springswaggerconfig

定義一個或多個swaggerspringmvcplugin執行個體，通過springs @bean注解

二、碰到的問題

關于@api注解

在swagger annotation中：

api表示一個開放的api，可以通過description簡要描述該api的功能。

在一個@api下，可有多個@apioperation，表示針對該api的crud操作。在apioperation annotation中可以通過value，notes描述該操作的作用，response描述正常情況下該請求的傳回對象類型。

在一個apioperation下，可以通過apiresponses描述該api操作可能出現的異常情況。

apiparam用于描述該api操作接受的參數類型

再接着，為項目的model對象添加swagger annotation，這樣swagger scanner可以擷取更多關于model對象的資訊。

通過上面的步驟，項目已經具備了提供swagger格式的api資訊的能力，接下來，我們把這些資訊和swagger ui內建，以非常美觀，實用的方式把這些api資訊展示出來。

和swagger ui的內建

然後，修改index.html, 把swagger ui對象中的url替換為自己的api路徑。

最後，為了能通路到該頁面，還需要在service的initialize方法中，添加assetsbundle

最後的效果圖：

三、評價

swagger可以充目前後端交流的重要橋梁，友善快捷。很實用。

swagger項目允許你生産，顯示和消費你自己的restful服務。不需要代理和第三方服務。是一個依賴自由的資源集合，它能通過swagger api動态的生成漂亮的文檔和沙盒,因為swagger ui沒有依賴，你可以把他部署到任何伺服器環境或者是你自己的機器。

四、參考資料

github：