Swagger Annotation 詳解（建議收藏）

轉自：https://www.jianshu.com/p/b0b19368e4a8

作者：楊梅泡酒

在軟件開發行業，管理文檔是件頭疼的事。不是文檔難於撰寫，而是文檔難於維護，因為需求與代碼會經常變動，尤其在采用敏捷軟件開發模式的系統中。好的工具能夠提高團隊溝通效率，保證系統質量以及縮短項目的交付周期。反之，差的管理工具，會嚴重影響溝通效率，增加系統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>