Swagger 记录包含枚举（Enum）参数的文档

教程

1、概览

本文将带你了解如何使用 swagger-maven-plugin 来在 Swagger 中记录枚举，并在 Swagger 编辑器中验证生成的 JSON 文档。

2、Swagger 是啥？

Swagger 是一种开源工具，用于定义基于 REST 的 API。在当今世界，大多数组织都在向微服务和 API 优先的方向发展。Swagger 在设计和记录 API 方面非常方便。它还提供了 Swagger 编辑器、Swagger UI 和 Swagger CodeGen 等各种工具来协助 API 开发。

此外，Swagger 是 OpenAPI 规范或 OAS 的一种实现，OAS 定义了一套用于开发 REST API 的标准，有助于全球各地的组织将编写 API 的过程标准化。

我们应用生成的 JSON 文件也将遵循 OpenAPI 规范。

在 Swagger 中使用 Enum 是个有必要的，有些 API 需要用户只能使用一组特定的预定义值。这些预定义的常量值被称为枚举（Enum）。同样，当 Swagger 公开 API 时，需要要确保用户从这组预定义值中选择一个值，而不是任意的值。

换句话说，需要在 swagger.json 文件中记录枚举，让用户知道可选的选项。

3、实现

实现一个 POST API，用于为组织招聘特定角色的员工（Employee）。角色只能是以下角色之一：Engineer、Clerk、Driver 或 Janitor。

创建 Role 枚举，其中包含 Employee 角色的所有可能值，然后创建一个 Employee 类，将角色作为其属性之一。

UML 图如下：

UML 图

要使用 Swagger 生成文档，首先，要在应用中导入并配置 swagger-maven-plugin。其次，需要在代码中添加所需的注解，最后，构建项目并在 swagger 编辑器中验证生成的 swagger 文档或 swagger.json。

3.1、导入和配置插件

在 pom.xml 文件中的 plugin 节点添加 swagger-maven-plugin，并进行配置。

<plugin>
    <groupId>com.github.kongchen</groupId>
    <artifactId>swagger-maven-plugin</artifactId>
    <version>3.1.1</version>
    <configuration>
        <apiSources>
            <apiSource>
                <springmvc>false</springmvc>
                <locations>com.baeldung.swaggerenums.controller</locations>
                <schemes>http,https</schemes>
                <host>baeldung.com</host>
                <basePath>/api</basePath>
                <info>
                    <title>Baeldung - Document Enum</title>
                    <version>v1</version>
                    <description>This is a Baeldung Document Enum Sample Code</description>
                    <contact>
                        <email>pmurria@baeldung.com</email>
                        <name>Test</name>
                    </contact>
                    <license>
                        <url>https://www.apache.org/licenses/LICENSE-2.0.html</url>
                        <name>Apache 2.0</name>
                    </license>
                </info>
                <swaggerDirectory>generated/swagger-ui</swaggerDirectory>
            </apiSource>
        </apiSources>
    </configuration>
    <executions>
        <execution>
            <phase>compile</phase>
            <goals>
                <goal>generate</goal>
            </goals>
        </execution>
     </executions>
 </plugin>
  • locations：指定了包含 @Api 的包或类，多个的话用分号隔开。
  • info：设置元数据。Swagger-ui 使用这些数据来显示信息。
  • swaggerDirectory：定义了 swagger.json 文件的路径。

3.2、记录枚举

为了在 Swagger 中记录枚举，需要使用注解 @ApiModel 来声明 model。

在本例中，创建了一个枚举 Role，它有四个可能的值 - Engineer、Clerk、Driver 和 Janitor。要记录这个枚举，需要在枚举 Role 中添加 @ApiModel。换句话说，这将让 Swagger 知道 model 的存在。在 Employee 类中，用 @ApiModel 对 Employee 进行注解，并用 @ApiModelProperty 对 Role 进行注解。

如下：

@ApiModel
public class Employee {
    @ApiModelProperty
    public Role role;

   // get / set 方法省略
}

@ApiModel
public enum Role {
    Engineer, Clerk, Driver, Janitor;
}

接下来，创建一个 @Path 为 /hire 的 API，并使用 Employee Model 作为 hireEmployee 方法的参数。必须在 HireController 中添加 @Api，这样 swagger-maven-plugin 就会感知并将其视为文档：

@Api
@Path(value="/hire")
@Produces({"application/json"})
public class HireController {

    @POST
    @ApiOperation(value = "This method is used to hire employee with a specific role")
    public String hireEmployee(@ApiParam(value = "role", required = true) Employee employee) {
        return String.format("Hired for role: %s", employee.role.name());
    }
}

3.3、生成 Swagger 文档

运行以下命令，构建项目并生成 Swagger 文档：

mvn clean install

构建完成后，插件将在 generated/swagger-ui 或插件中配置的位置生成 swagger.json 文件。

查看该文件，你可以看到 employee 属性中记录的枚举 Role 及其所有可能的值。

"definitions" : {
  "Employee" : {
    "type" : "object",
    "properties" : {
      "role" : {
        "type" : "string",
        "enum" : [ "Engineer", "Clerk", "Driver", "Janitor" ]
      }
    }
  }
}

现在，通过 在线 swagger 编辑器 用生成的 JSON 生成可视化文档，并查看枚举参数 Role：

Swagger 在线编辑器

4、总结

本文介绍了什么是 Swagger，以及如何通过 swagger-maven-plugin 创建并记录包含枚举参数的 API 文档。

参考：https://www.baeldung.com/swagger-enum