使REST API易于使用的真正關鍵是好的文檔。 但是，即使您的文檔做得不錯，您也需要設置公司流程的權利，以正確，及時地發布它。 確保利益相關者按時收到是一回事，但是您也要負責API和文檔中的更新。 自動完成此過程可輕松解決問題，因為您的文檔不再是靜態交付的，而變成了活物。 在上一篇文章中，我討論了如何將Swagger與帶有Jersey的Spring應用程序集成。 現在該向您展示如何創建文檔并將其發布給其他人查看。

在深入了解實際文檔之前，讓我們從其形式和屬性開始一些注意。 我們將使用批注為我們的API提供元數據，從而回答問題的方式。 但是為什么呢？ 一方面，我們正在為已經存在注釋的地方（如API端點或控制器）提供新的注釋（與Spring MVC集成的情況下）。 但另一方面，這種方法在一次交付中綁定應用程序，API和文檔的發布周期方面具有突出的優勢。 使用這種方法，我們可以創建和管理小的內聚單元，從而確保對文檔及其版本進行適當的分段。

創建端點文檔

一切都從端點開始。 為了使Swagger知道您的端點，您需要使用@Api注釋對您的類進行注釋。 基本上，您要做的就是命名端點并為用戶提供一些說明。 這正是我在以下代碼段中所做的。 如果您需要使用API??文檔進行更詳細的介紹，請查看下面的@Api注釋說明。

package com.jakubstas.swagger.rest;/*** REST endpoint for user manipulation.*/ @Api(value = "users", description = "Endpoint for user management") @Path("/users") public class UsersEndpoint {... }

要驗證結果，只需從basePath變量中輸入URL，然后在瀏覽器中輸入/api-docs 。 這是API資源清單所在的地方。 在注釋了三個端點并訪問http://[hostname]:[port]/SpringWithSwagger/rest/api-docs/之后，您可能會看到類似于以下片段的內容：

{"apiVersion":"1.0","swaggerVersion":"1.2","apis":[{"path":"/users","description":"Endpoint for user management"},{"path":"/products","description":"Endpoint for product management"},{"path":"/employees","description":"Endpoint for employee listing"}] }

但是，請注意，為了使API出現在API列表中，您必須至少使用Swagger注釋來注釋一個API方法。 如果沒有注釋任何方法（或尚未提供任何方法），則將不處理和發布API文檔。

@Api批注

描述頂級API。 具有@Api批注的類將包含在資源列表中。

注釋參數：

• value – Api的簡短說明
• description -此類的一般描述
• basePath –所有@Path元素之前的基本路徑
• position –資源清單中此Api的可選顯式排序
• produces -此Api produces內容類型
• consumes –此Api consumes媒體類型
• protocols –該Api所需的協議（即https）
• authorizations -此Api所需的授權

運營文件

現在，讓我們進入API文檔的關鍵部分。 操作文檔基本上有兩個主要部分-操作描述和響應描述。 讓我們從操作說明開始。 使用注釋@ApiOperation提供了某些方法的詳細說明，其響應，HTTP方法以及下面注釋說明中提供的其他有用信息。 在以下代碼示例中可以看到Swagger的操作聲明的示例。

@ApiOperation批注

描述針對特定路徑的操作或通常為HTTP方法。 具有等效路徑的操作在Api聲明的數組中分組。

注釋參數：

• value –操作簡要說明
• notes –操作的詳細說明
• response操作中的默認響應類
• responseContainer –如果響應類在容器內，請在此處指定
• tags –目前尚未在閱讀器中實施，保留以備將來使用
• httpMethod – HTTP方法，即GET ， PUT ， POST ， DELETE ， PATCH ， OPTIONS
• position –允許在Api聲明中對操作進行顯式排序
• nickname –操作的昵稱，以覆蓋注釋掃描程序檢測到的昵稱
• produces -此Api produces內容類型
• consumes –此Api consumes媒體類型
• protocols –該Api所需的協議（即https）
• authorizations -此Api所需的授權

您可能會注意到@ApiOperation批注中使用了response參數，該參數指定了操作的響應類型（返回類型）。 如您所見，該值可以與方法返回類型不同，因為它僅用于API文檔。

@GET @Path("/{userName}") @Produces(MediaType.APPLICATION_JSON) @ApiOperation(value = "Returns user details", notes = "Returns a complete list of users details with a date of last modification.", response = User.class) @ApiResponses(value = {@ApiResponse(code = 200, message = "Successful retrieval of user detail", response = User.class),@ApiResponse(code = 404, message = "User with given username does not exist"),@ApiResponse(code = 500, message = "Internal server error")} ) public Response getUser(@ApiParam(name = "userName", value = "Alphanumeric login to the application", required = true) @PathParam("userName") String userName) {... }

接下來，看看@ApiParam 。 向客戶描述滿足您的需求所需的內容總是很有用的。 這是@ApiParam批注的主要目的。 無論您使用的是路徑還是查詢參數，都應始終提供此參數代表的含義。

@ApiParam批注

表示Api操作中的單個參數。 參數是操作的輸入。

注釋參數：

• name –參數名稱
• value –參數說明
• defaultValue –默認值–如果沒有給出JAX-RS @DefaultValue
• allowableValues –該端點接受的值的描述
• required –指定參數是否為必需
• access –指定一個可選的訪問值以在Filter實現中進行Filter 。 如果用戶無權訪問某些參數，則可以隱藏這些參數
• allowMultiple –指定參數是否可以提供多個值

最后，讓我們看一下用消息和HTTP代碼記錄實際方法響應的方式。 Swagger帶有@ApiResponse批注，當使用@ApiResponses包裝器進行包裝時，可以多次使用。 這樣，您可以覆蓋代碼的所有替代執行流程，并為API客戶端提供完整的API操作說明。 每個響應都可以用HTTP返回碼，結果描述和結果類型來描述。 有關@ApiResponse更多詳細信息，請參見下面的描述。

@ApiResponse批注

ApiResponse表示來自服務器的一種響應。 這可以用來描述成功代碼以及錯誤。 如果您的Api具有不同的響應類別，則可以在此處通過將響應類別與響應代碼相關聯來描述它們。 注意，Swagger不允許單個響應代碼具有多種響應類型。

注釋參數：

• code –描述的響應代碼
• message –響應中的人類可讀消息
• response –描述消息有效負載的可選響應類

使用這些注釋非常簡單，并提供了結構良好的方法來描述API的功能。 如果要檢查文檔的外觀，只需將@Api批注中的參數value的值附加到指向資源列表的URL上，輸入指向端點之一的API文檔的URL。 注意不要誤輸入@Path注釋的值（除非它們具有相同的值）。 在我的示例中，所需的URL是http://[hostname]:[port]/SpringWithSwagger/rest/api-docs/users 。 您應該能夠看到類似于以下代碼片段的輸出：

{ "apiVersion":"1.0","swaggerVersion":"1.2","basePath":"http://[hostname/ip address]:[port]/SpringWithSwagger/rest","resourcePath":"/users","apis":[ { "path":"/users/{userName}","operations":[ { "method":"GET","summary":"Returns user details","notes":"Returns a complete list of users details with a date of last modification.","type":"User","nickname":"getUser","produces":[ "application/json"],"authorizations":{ },"parameters":[ { "name":"userName","description":"Alphanumeric login to application","required":true,"type":"string","paramType":"path","allowMultiple":false}],"responseMessages":[ { "code":200,"message":"Successful retrieval of user detail","responseModel":"User"},{ "code":404,"message":"User with given username does not exist"},{ "code":500,"message":"Internal server error"}]}]}],"models":{"User":{"id":"User","properties": {"surname":{"type":"string"},"userName":{"type":"string"},"lastUpdated":{"type":"string","format":"date-time"},"avatar":{"type":"array","items":{"type":"byte"}},"firstName":{"type":"string"},"email":{"type":"string"}}}} }

創建模型文檔

通過向前面的示例中的幾個批注的響應參數提供User類，我設法在API文檔中引入了新的未記錄元素。 Swagger能夠提取有關User類的所有結構性數據，而無需考慮與API的相關性。 為了抵消這種影響，Swagger提供了兩個注釋，以向API用戶提供其他信息并限制模型的可見性。 要標記由Swagger處理的模型類，只需將@ApiModel放在類的頂部。 與往常一樣，您可以提供描述以及繼承配置。 有關更多信息，請參見下面的@ApiModel描述。

@ApiModel批注

REST-api中使用的bean類。 假設您有一個接口@PUT @ApiOperation(...) void foo(FooBean fooBean) ，沒有直接的方法來查看FooBean將具有哪些字段。 該注釋旨在給出FooBean的描述，然后使用@ApiModelProperty字段進行注釋。

注釋參數：

• value –提供此類的提要
• description –提供對該類的詳細說明
• parent –為模型提供超類，以允許描述繼承
• discriminator –對于具有基類的模型，可以為多態用例提供鑒別符
• subTypes

您需要做的最后一件事是使用@ApiModelProperty注釋對類成員進行注釋，以為每個類成員提供文檔。 在下面的類中可以看到一個簡單的例子。

package com.jakubstas.swagger.model;@ApiModel public class User {private String userName;private String firstName;private String surname;private String email;private byte[] avatar;private Date lastUpdated;@ApiModelProperty(position = 1, required = true, value = "username containing only lowercase letters or numbers")public String getUserName() {return userName;}public void setUserName(String userName) {this.userName = userName;}@ApiModelProperty(position = 2, required = true)public String getFirstName() {return firstName;}public void setFirstName(String firstName) {this.firstName = firstName;}@ApiModelProperty(position = 3, required = true)public String getSurname() {return surname;}public void setSurname(String surname) {this.surname = surname;}@ApiModelProperty(position = 4, required = true)public String getEmail() {return email;}public void setEmail(String email) {this.email = email;}@JsonIgnorepublic byte[] getAvatar() {return avatar;}public void setAvatar(byte[] avatar) {this.avatar = avatar;}@ApiModelProperty(position = 5, value = "timestamp of last modification")public Date getLastUpdated() {return lastUpdated;}public void setLastUpdated(Date lastUpdated) {this.lastUpdated = lastUpdated;} }

如果您需要提供有關模型的更多詳細信息，請檢查@ApiModelProperty以下描述：

@ApiModelProperty批注

ApiModelProperty描述了模型類中的屬性。 根據模型掃描儀的配置和使用方式，注釋可以應用于方法，屬性等。

注釋參數：

• value –提供此屬性的易于理解的摘要
• allowableValues –如果可以設置的值受到限制，則可以在此處設置它們。 以逗號分隔的列表形式registered, active, closed
• access –指定一個可選的訪問值以在Filter實現中進行Filter 。 如果用戶無權訪問某些參數，則可以隱藏這些參數
• notes –物業的詳細說明
• dataType –數據類型。 請參閱文檔以獲取受支持的數據類型。 如果數據類型是自定義對象，請設置其名稱，或不設置任何名稱。 如果是枚舉，請為枚舉常量使用'string'和allowableValues
• required –是否required該屬性，默認為false
• position –允許在模型中顯式排序屬性。 由于反射不能保證順序，因此應指定屬性順序，以使模型在不同的VM實現和版本之間保持一致

如果您仔細遵循這些說明，那么您應該在前面提到的URL的json中獲得完整的API文檔。 以下僅是結果json中與模型相關的部分，現在提供了文檔。

{..."models":{ "User":{ "id":"User","description":"","required":[ "userName","firstName","surname","email"],"properties":{ "userName":{ "type":"string","description":"username containing only lowercase letters or numbers"},"firstName":{ "type":"string"},"surname":{ "type":"string"},"email":{ "type":"string"},"lastUpdated":{ "type":"string","format":"date-time","description":"timestamp of last modification"}}}} }

下一步是什么？

如果按照所有步驟進行操作，您現在應該擁有可以由自動化工具發布或進一步處理的有效API文檔。 在我的下一篇名為Swagger的Spring Rest API –公開文檔中，我將展示如何使用Swagger UI模塊展示API文檔。 該微型系列中使用的代碼在GitHub上發布，并提供了所有討論的功能和工具的示例。 請享受！

翻譯自: https://www.javacodegeeks.com/2014/10/spring-rest-api-with-swagger-creating-documentation.html

總結

以上是生活随笔為你收集整理的带有Swagger的Spring Rest API –创建文档的全部內容，希望文章能夠幫你解決所遇到的問題。

如果覺得生活随笔網站內容還不錯，歡迎將生活随笔推薦給好友。