Swagger/OpenAPI V3注释 - 在Swagger注释中使用枚举值

Question

我正在使用Swagger/OpenAPI V3注释为我们的应用程序创建API描述，这些注释来自以下依赖项：

<dependency>
    <groupId>org.springdoc</groupId>
    <artifactId>springdoc-openapi-ui</artifactId>
    <version>1.1.45</version>
</dependency>

其中一个注释是@Schema注释，它接受一个名为allowableValues的属性，该属性允许一个字符串数组：

@Schema(description = "example", 
        allowableValues = {"exampleV1", "exampleV2"}, 
        example = "exampleV1", required = true)
private String example;

现在，我想使用我们的Enum类上构建的自定义方法来返回允许的字符串数组，这样就不需要每次添加类型到Enum时都添加它。这样我们可以像这样使用它：

public enum ExampleEnum {
    EXAMPLEV1, EXAMPLEV2;
    public static String[] getValues() {...}
}

@Schema(description = "example", 
        allowableValues = ExampleEnum.getValues(), 
        example = "exampleV1", required = true)
private String example;

现在这段代码无法编译，因为执行注解时方法是未知的。

在Swagger V3注解属性值中是否存在允许使用Enums的解决方案？

查看了下面的资源:

• https://swagger.io/docs/specification/data-models/enums/

您可以在全局组件部分定义可重用的枚举，并通过$ref引用它们。

最坏的情况是我确实可以将其定义在一个常量位置，并在将类型添加到枚举后只需要添加到另一个位置。但我首先想探索上述提到的解决方案是否可行。

• https://github.com/swagger-api/swagger-core/wiki/Swagger-2.X---Annotations#schema

没有关于使用任何类或动态生成的值的说明。

• Enum in swagger

是关于在Swagger中记录枚举，而不是在Swagger注解API中使用它们。

- bramdc

Answer 1

尝试使用@Schema(implementation = ExampleEnum.class, ...)，您可以添加其他所需的所有属性。 我需要更多有关您实现的信息，但请先尝试这个。

- Tarnished-Coder

---

很不幸，我已经没有代码了，所以无法再试一下了... 有其他人可以确认一下吗？ - bramdc

当我在控制器的一个参数中添加@Schema(implementation = MyEnum.class)时，这似乎对我无效。 - ojathelonius

@ojathelonius 请分享您的代码以及更多上下文信息，以便解决您的问题。 - Tarnished-Coder

我确认它在OpenAPI v2上运行良好，我在我的代码的几个地方进行了验证，这对我帮助很大！谢谢！ - RAM237

对于任何试图使用数组的人：请使用@ArraySchema(schema = @Schema(implementation = ExampleEnum.class))！ - Snackaholic

Answer 2

在我的情况下，我已经在我的枚举类型中添加了一个注释：

@Schema(enumAsRef = true)
public enum WikipediaLanguage {
  ...
}

然后，只需将其作为参数的注释使用在REST控制器方法的参数中：

@Parameter(
    description = "Language of the Wikipedia in use",
    required = true
) @RequestParam WikipediaLanguage lang

- Benjamín Valero