掌握 Swagger enum 的最佳实践指南 - HelloWorld开发者社区

enum 是 Swagger 规范中用来定义枚举类型的一种方式。它允许开发者在 API 文档中明确列出该接口的参数、返回值或请求体中可接受的枚举值。通过使用 Swagger enum，开发者可以更清晰地描述 API 的输入和输出，提高 API 文档的可读性和可维护性。

掌握 Swagger enum 的最佳实践指南

enum 使用场景

在以下情况下，使用 Swagger enum 功能是非常有意义的：

当 API 接口 的参数或返回值具有预定义的枚举值时，使用 Swagger enum 可以明确告知使用者可以选择的选项。
当 API 接口有多个可能的状态时，使用 Swagger enum 可以减少开发者需要查看 API 源代码的次数，从而更快地理解 API 的用法。
当使用了前后端分离的开发架构时，Swagger enum 可以作为后端开发人员与前端开发人员之间统一枚举值的约定。

enum 用法介绍

在 Swagger 规范中，使用 enum 关键字定义枚举值。例如，我们可以在参数定义中使用 enum 来明确指定参数的可选值：

parameters:
  - name: status
    in: query
    required: true
    type: string
    enum:
      - active
      - inactive

在这个示例中，status 参数的可能取值只能是 active 或 inactive。

实践案例

当使用 Swagger Editor 来编辑和运行 Swagger 定义时，可以使用以下示例在枚举类型中使用 Swagger enum：

swagger: "2.0"
info:
  title: Example API
  version: 1.0.0

paths:
  /pets:
    post:
      summary: Add a new pet to the store
      parameters:
        - name: petSize
          in: query
          description: The size of the pet
          required: true
          type: string
          enum:
            - small
            - medium
            - large
      responses:
        200:
          description: OK

在 Swagger Editor 中，将以上文本粘贴到编辑器中，你会看到右侧的 Swagger UI 将显示你的 API。你可以尝试发送请求以查看效果。

当你向/pets发送 POST 请求时，你将需要在查询参数中传递petSize的值。尝试将petSize设置为small、medium或large之外的其他值，并发送请求。你将会看到 Swagger UI 会标示出你的请求是无效的，并在文档中明确列出可选的枚举值。

这个示例可以在 Swagger Editor 中运行并进行测试，以展示 Swagger enum 的使用方式。

掌握 Swagger enum 的最佳实践指南

在 SpringBoot 中配置注解

在 Spring Boot 中，你可以使用@ApiModelProperty注解来配置 Swagger 枚举类型。

首先，确保在你的项目中添加了 Swagger 的依赖。在pom.xml文件中添加以下依赖：

<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger2</artifactId>
    <version>2.9.2</version>
</dependency>
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger-ui</artifactId>
    <version>2.9.2</version>
</dependency>

接下来，在你的枚举字段上使用@ApiModelProperty注解进行配置。例如，假设你有一个名为Pet的实体类，其中包含一个size字段，它使用了枚举类型：

import io.swagger.annotations.ApiModelProperty;

public class Pet {
    @ApiModelProperty(value = "The size of the pet", allowableValues = "SMALL, MEDIUM, LARGE")
    private Size size;

    // ...
}

在上述示例中，我们使用了@ApiModelProperty注解来指定字段的描述和可选值。allowableValues属性用于指定可选的枚举值，每个值用逗号分隔。

然后，使用@ApiModel注解来对实体类进行配置：

import io.swagger.annotations.ApiModel;

@ApiModel(description = "Pet entity")
public class Pet {
    // ...
}

接下来，配置 Swagger 的 Docket Bean 来启用 Swagger 并设置相关配置。在你的 Spring Boot 应用程序主类中，添加以下代码：

import springfox.documentation.swagger2.annotations.EnableSwagger2;

@SpringBootApplication
@EnableSwagger2
public class YourApplication {

    public static void main(String[] args) {
        SpringApplication.run(YourApplication.class, args);
    }

    @Bean
    public Docket api() {
        return new Docket(DocumentationType.SWAGGER_2)
            .select()
            .apis(RequestHandlerSelectors.any())
            .paths(PathSelectors.any())
            .build();
    }
}

以上代码配置了一个名为api的 Docket Bean 来启用 Swagger，并设置了扫描所有请求处理程序和路径的条件。

然后，启动你的 Spring Boot 应用程序并访问 Swagger UI 界面（通常是http://localhost:8080/swagger-ui.html）。你将看到你的枚举类型字段显示了可选的枚举值。