带有Swagger的Spring Rest API –创建文档

最新推荐文章于 2021-11-24 17:56:24 发布

dnc8371

最新推荐文章于 2021-11-24 17:56:24 发布

阅读量111

点赞数

文章标签： python java 大数据 http web

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

    @JsonIgnore
    public 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上发布，并提供了所有讨论的功能和工具的示例。请享受！