Swagger Annotation 詳解

在軟件開發行業，管理文檔是件頭疼的事。不是文檔難於撰寫，而是文檔難於維護，由於需求與代碼會常常變更，尤爲在採用敏捷軟件開發模式的系統中。好的工具可以提升團隊溝通效率，保證系統質量以及縮短項目的交付週期。反之，差的管理工具，會嚴重影響溝通效率，增長系統bug數量，而且延誤產品的上線日期。因此選用合理與合適的軟件開發文檔管理工具十分重要，真正讓開發者作到「高高興興地把活幹完，早點回家吃飯打遊戲」。

Swagger是什麼？

Swagger 是一款目前世界最流行的API管理工具。但目前Swagger已經造成一個生態圈，可以管理API的整個生命週期，從設計、文檔到測試與部署。Swagger有幾個重要特性：

• 代碼侵入式註解
• 遵循YAML文檔格式
• 很是適合三端（PC、iOS及Android）的API管理，尤爲適合先後端徹底分離的架構模式。
• 減小沒有必要的文檔，符合敏捷開發理念
• 功能強大

Swagger擁有衆多不一樣語言和平臺的開源實現與工具，主要有：

• Swagger UI，基於Swagger-compliant API的一套能夠展現優美文檔的Web應用。
• Swagger Editor，一款以YAML格式編輯與管理API的工具，同時支持JSON格式的文檔描述。
• Swagger-Core，Swagger的Java/Scala實現，並已集成 JAX-RS (Jersey, Resteasy, CXF...), Servlets與Play Framework。
• Swagger-JS，Swagger的Javascript版本實現。

更多的列表能夠參考此處。

尤爲要注意的是Swagger UI，它是Swagger的Web頁面展示形式，可以對符合swagger規範的文件進行解析與顯示。經過友好的頁面，能夠對API進行分組管理、文檔顯示以及實現mock測試。因此在大多數情形下，都使用Swagger UI實現對API的管理與展示。

 

API分組列表

 

API Mock測試

Swagger UI的安裝

Swagger UI是一個Web應用程序，因此能夠單獨部署使用。能夠從這裏下載Swagger UI，而後根據文檔說明進行安裝與配置。

對於以Java與Spring Boot做爲後臺開發語言和框架而言，專門有一個開源插件springfox同時實現了Swagger UI及Swagger-Core。這個插件能夠很方便地利用構建工具Maven或Gradle引入與管理。本文如下部分將着重講述有關這個插件的swagger相關注解。

Swagger Annotation分析

對於java版本的swagger annotations比較多，本着精簡與必要的原則，不會對全部annotation及每一個annotation的全部屬性進行描述，僅選擇重要且工做中經常使用的部分進行說明。

Swagger的annotation主要分爲兩類，一類是對Model的註解；另外一類是對API的註解。

API的註解

對於API的設計，通常傾向於將功能相同的API歸集爲一組。在Spring Boot中，利用Controller來實現，每一個Controller裏包含若干個REST API，而每一個API都有輸入及輸出值。因此swagger對API的註解也是參照這個層級來劃分與實現的。其邏輯結果以下圖：

 

Swagger Annotation 邏輯結構圖

• @Api
  該註解將一個Controller（Class）標註爲一個swagger資源（API）。在默認狀況下，Swagger-Core只會掃描解析具備@Api註解的類，而會自動忽略其餘類別資源（JAX-RS endpoints，Servlets等等）的註解。該註解包含如下幾個重要屬性：
  • tags
    API分組標籤。具備相同標籤的API將會被歸併在一組內展現。
  • value
    若是tags沒有定義，value將做爲Api的tags使用
  • description
    API的詳細描述，在1.5.X版本以後再也不使用，但實際發如今2.0.0版本中仍然可使用
• @ApiOperation
  在指定的（路由）路徑上，對一個操做或HTTP方法進行描述。具備相同路徑的不一樣操做會被歸組爲同一個操做對象。不一樣的HTTP請求方法及路徑組合構成一個惟一操做。此註解的屬性有：
  • value
    對操做的簡單說明，長度爲120個字母，60個漢字。
  • notes
    對操做的詳細說明。
  • httpMethod
    HTTP請求的動做名，可選值有："GET", "HEAD", "POST", "PUT", "DELETE", "OPTIONS" and "PATCH"。
  • code
    默認爲200，有效值必須符合標準的HTTP Status Code Definitions。
• @ApiImplicitParams
  註解ApiImplicitParam的容器類，以數組方式存儲。
• @ApiImplicitParam
  對API的單一參數進行註解。雖然註解@ApiParam同JAX-RS參數相綁定，但這個@ApiImplicitParam註解能夠以統一的方式定義參數列表，也是在Servelet及非JAX-RS環境下，惟一的方式參數定義方式。注意這個註解@ApiImplicitParam必須被包含在註解@ApiImplicitParams以內。能夠設置如下重要參數屬性：
  • name
    參數名稱
  • value
    參數的簡短描述
  • required
    是否爲必傳參數
  • dataType
    參數類型，能夠爲類名，也能夠爲基本類型（String，int、boolean等）
  • paramType
    參數的傳入（請求）類型，可選的值有path, query, body, header or form。
• @ApiParam
  增長對參數的元信息說明。這個註解只能被使用在JAX-RS 1.x/2.x的綜合環境下。其主要的屬性有：
  • required
    是否爲必傳參數
  • value
    參數簡短說明
• @ApiResponses
  註解@ApiResponse的包裝類，數組結構。即便須要使用一個@ApiResponse註解，也須要將@ApiResponse註解包含在註解@ApiResponses內。
• @ApiResponse
  描述一個操做可能的返回結果。當REST API請求發生時，這個註解可用於描述全部可能的成功與錯誤碼。能夠用，也能夠不用這個註解去描述操做的返回類型，但成功操做的返回類型必須在@ApiOperation中定義。若是API具備不一樣的返回類型，那麼須要分別定義返回值，並將返回類型進行關聯。但Swagger不支持同一返回碼，多種返回類型的註解。注意：這個註解必須被包含在@ApiResponses註解中。
  • code
    HTTP請求返回碼。有效值必須符合標準的HTTP Status Code Definitions。
  • message
    更加易於理解的文本消息
  • response
    返回類型信息，必須使用徹底限定類名，好比「com.xyz.cc.Person.class」。
  • responseContainer
    若是返回類型爲容器類型，能夠設置相應的值。有效值爲 "List", "Set" or "Map"，其餘任何無效的值都會被忽略。

Model的註解

對於Model的註解，Swagger提供了兩個：@ApiModel及@ApiModelProperty，分別用以描述Model及Model內的屬性。

• @ApiModel
  提供對Swagger model額外信息的描述。在標註@ApiOperation註解的操做內，全部的類將自動被內省（introspected），但利用這個註解能夠作一些更加詳細的model結構說明。主要屬性有：
  • value
    model的別名，默認爲類名
  • description
    model的詳細描述
• @ApiModelProperty
  對model屬性的註解，主要的屬性值有：
  • value
    屬性簡短描述
  • example
    屬性的示例值
  • required
    是否爲必須值

關於Token問題

考慮到安全的問題，每次請求API須要對用戶進行驗證與受權。目前主流的驗證方式採用請求頭部（request header）傳遞token，即用戶登陸以後獲取一個token，而後每次都使用這個token去請求API。若是想利用swagger-UI進行API測試，必須顯式爲每一個須要驗證的API指定token參數。這時能夠爲每一個操做添加一個註解@ApiImplicitParams，具體代碼以下：
<code>
@ApiImplicitParams({@ApiImplicitParam(name = "TOKEN", value = "Authorization token", required = true, dataType = "string", paramType = "header")})
</code>

原文連接：https://www.jianshu.com/p/b0b19368e4a8