将枚举作为组件的 Swagger 注解

Question

我有一个枚举：

public enum UserType {
  ADMIN("Admin"),
  GUEST("Guest"),
  SUPERVIOR("Supervisor"),
  NORMAL("Normal");

  private final String type;

  UserType(final String type) {
    this.type = type;
  }

我将它用作带有 Swagger 注释的查询参数：

@GET
@AsyncTimed
@Path("/all")
void all(
    @ApiParam @PathParam(USER_ID) @Parameter(in = ParameterIn.PATH, name = USER_ID, required = true) final UserId userId,
    @QueryParam(TYPES) final Set<UserType> userTypes,
    @Suspended final AsyncResponse asyncResponse
);

然而，生成的 OpenAPI 文件并没有从枚举中创建组件，而是给出：

get:
  parameters:
  - name: UserId
    in: path
    required: true
    schema:
      $ref: '#/components/schemas/UserId'
  - name: Types
    in: query
    schema:
      uniqueItems: true
      type: array
      items:
        type: string
        enum:
          - ADMIN
          - GUEST
          - SUPERVISOR
          - NORMAL

有没有办法让枚举成为组件模式？如果我在其他组件中使用此枚举，这些组件也会使用enum:而不是$ref.

Answer 1

您需要用 注释枚举和/或相应的参数@Schema(..., enumAsRef=true)。