1. 概述
在这个教程中，我们将学习如何使用swagger-maven-plugin来为Swagger文档化枚举，并在Swagger编辑器中验证生成的JSON文档。
2. Swagger是什么？
Swagger是一个开源工具，用于定义基于REST的API。在当今世界，大多数组织正在转向微服务和API优先的方法。Swagger对于设计和文档化API非常有用。它还提供了如Swagger Editor、Swagger UI和Swagger CodeGen等工具，以辅助API开发。
此外，Swagger是OpenAPI规范（或OAS）的实现，它定义了REST API开发的标准集；因此，它帮助全球的组织标准化编写API的过程。
我们的应用程序生成的JSON文件也将遵循OpenAPI规范。
让我们理解在Swagger中枚举的重要性。有些API需要用户使用预定义的一组值。这些预定义的常量值称为枚举。同样，当Swagger暴露API时，我们希望确保用户从这个预定义的集合中选择值，而不是自由文本。换句话说，我们需要在我们的swagger.json文件中文档化枚举，以便用户知道可能的值。
3. 实现
让我们通过一个REST API示例来了解实施过程。我们将实现一个POST API，为组织雇佣特定角色的员工。然而，角色只能是以下四种之一：Engineer、Clerk、Driver或Janitor。
我们将创建一个名为Role的枚举，包含所有可能的员工角色，并创建一个包含角色属性的类Employee。下面是更好地理解类及其关系的UML图：
要在Swagger中进行文档化，首先，我们需要导入并配置swagger-maven-plugin到我们的应用中。其次，我们需要在代码中添加所需的注解，最后构建项目并在Swagger编辑器中验证生成的Swagger文档或swagger.json。
3.1. 导入并配置插件
我们将使用swagger-maven-plugin，并需要将其添加到应用的pom.xml的依赖项中：
<dependency>
<groupId>com.github.kongchen</groupId>
<artifactId>swagger-maven-plugin</artifactId>
<version>3.1.1</version>
</dependency>
为了配置和启用此插件，我们将在pom.xml的plugins部分添加它：
- locations：这个标签指定包含@Api的包或类，用分号分隔。
- info：这个标签提供API的元数据。Swagger-ui使用这些数据来显示信息。
- swaggerDirectory：这个标签定义了
swagger.json文件的位置。
<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>[email protected]</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>
3.2. 文档化枚举
要在Swagger中文档化枚举，我们需要使用注解@ApiModel来声明模型。
在这个例子中，我们创建了一个名为Role的枚举，有四个可能的值：Engineer、Clerk、Driver和Janitor。由于我们需要文档化这个枚举，我们将@ApiModel添加到枚举Role上。换句话说，这将让Swagger知道模型的存在。在Employee类中，我们将Employee标记为@ApiModel，将Role标记为@ApiModelProperty。
我们的Employee、Role和HireController如下所示：
@ApiModel
public class Employee {
@ApiModelProperty
public Role role;
// standard setters and getters
}
@ApiModel
public enum Role {
Engineer, Clerk, Driver, Janitor;
}
接下来，我们将创建一个带有@Path为“/hire”的API，并使用Employee模型作为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文件。在定义部分，我们将看到枚举Role被文档化为员工属性中的所有可能值。
"definitions" : {
"Employee" : {
"type" : "object",
"properties" : {
"role" : {
"type" : "string",
"enum" : [ "Engineer", "Clerk", "Driver", "Janitor" ]
}
}
}
}
现在，我们将使用在线Swagger编辑器此处可视化生成的JSON。
4. 总结
在这篇教程中，我们讨论了Swagger是什么，以及它在组织API开发中的OpenAPI规范的重要性和价值。我们还创建并使用swagger-maven-plugin文档化了一个包含枚举的示例API。最后，我们使用Swagger编辑器来验证输出的生成JSON文档。
这个实现可以在GitHub上找到。