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

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

創(chuàng)建端點文檔

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

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

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

{"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出現(xiàn)在API列表中，您必須至少使用Swagger注釋來注釋一個API方法。 如果沒有注釋任何方法（或尚未提供任何方法），則將不處理和發(fā)布API文檔。

@Api批注

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

注釋參數(shù)：

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

運營文件

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

@ApiOperation批注

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

注釋參數(shù)：

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

您可能會注意到@ApiOperation批注中使用了response參數(shù)，該參數(shù)指定了操作的響應(yīng)類型（返回類型）。 如您所見，該值可以與方法返回類型不同，因為它僅用于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 。 向客戶描述滿足您的需求所需的內(nèi)容總是很有用的。 這是@ApiParam批注的主要目的。 無論您使用的是路徑還是查詢參數(shù)，都應(yīng)始終提供此參數(shù)代表的含義。

@ApiParam批注

表示Api操作中的單個參數(shù)。 參數(shù)是操作的輸入。

注釋參數(shù)：

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

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

@ApiResponse批注

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

注釋參數(shù)：

• code –描述的響應(yīng)代碼
• message –響應(yīng)中的人類可讀消息
• response –描述消息有效負(fù)載的可選響應(yīng)類

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

{ "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"}}}} }

創(chuàng)建模型文檔

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

@ApiModel批注

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

注釋參數(shù)：

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

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

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;} }

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

@ApiModelProperty批注

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

注釋參數(shù)：

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

如果您仔細(xì)遵循這些說明，那么您應(yīng)該在前面提到的URL的json中獲得完整的API文檔。 以下僅是結(jié)果json中與模型相關(guān)的部分，現(xiàn)在提供了文檔。

{..."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"}}}} }

下一步是什么？

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

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

總結(jié)

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

如果覺得生活随笔網(wǎng)站內(nèi)容還不錯，歡迎將生活随笔推薦給好友。