有時候一份清晰明了的接口文檔能夠極大地提高前後端雙方的溝通效率和開發效率。本文将介紹如何使用swagger生成接口文檔。
Swagger本質上是一種用于描述使用JSON表示的RESTful API的接口描述語言。Swagger與一組開源軟體工具一起使用，以設計、建構、記錄和使用RESTful Web服務。Swagger包括自動文檔，代碼生成和測試用例生成。
在前後端分離的項目開發過程中，如果後端同學能夠提供一份清晰明了的接口文檔，那麼就能極大地提高大家的溝通效率和開發效率。可是編寫接口文檔曆來都是令人頭痛的，而且後續接口文檔的維護也十分耗費精力。
最好是有一種方案能夠既滿足我們輸出文檔的需要又能随代碼的變更自動更新，而Swagger正是那種能幫我們解決接口文檔問題的工具。
這裡以gin架構為例，使用gin-swagger庫以使用Swagger 2.0自動生成RESTful API文檔。
想要使用gin-swagger為你的代碼自動生成接口文檔，一般需要下面三個步驟：
按照swagger要求給接口代碼添加聲明式注釋，具體參照聲明式注釋格式。
使用swag工具掃描代碼自動生成API接口文檔資料
使用gin-swagger渲染線上接口文檔頁面
在程式入口main函數上以注釋的方式寫下項目相關介紹資訊。
在你代碼中處理請求的接口函數（通常位于controller層）按如下方式寫上注釋：
上面注釋中參數類型使用了object，models.ParamPostList具體定義如下：
響應資料類型也使用的object，我個人習慣在controller層專門定義一個docs_models.go檔案來存儲文檔中使用的響應資料model。
編寫完注釋後，使用以下指令安裝swag工具：
在項目根目錄執行以下指令，使用swag工具生成接口文檔資料。
執行完上述指令後，如果你寫的注釋格式沒問題，此時你的項目根目錄下會多出一個docs檔案夾。
然後在項目代碼中注冊路由的地方按如下方式引入gin-swagger相關内容：
注冊swagger api相關路由
把你的項目程式運作起來，打開浏覽器通路http://localhost:8080/swagger/index.html就能看到Swagger 2.0 Api文檔了
gin-swagger同時還提供了DisablingWrapHandler函數，友善我們通過設定某些環境變量來禁用Swagger。例如：
此時如果将環境變量NAME_OF_ENV_VARIABLE設定為任意值，則/swagger/*any将傳回404響應，就像未指定路由時一樣
作者：張亞飛
gitee：https://gitee.com/zhangyafeii
本文版權歸作者和部落格園共有，歡迎轉載，但未經作者同意必須保留此段聲明，且在文章頁面明顯位置給出原文連接配接。