OpenAPI 3.0在不同模式中重用枚举值

Question

我有多个请求体需要使用相同的枚举，但我很难跨多个模式引用单个定义。

在我的< code>openapi.yaml文件中，我包含了:

components:
  schemas:
    Widget:
      type: string
      enum:
        - THING

在我为 POST/PUT 请求设置的正文定义中，我包括：

  widget:
    schema:
      $ref: '#/../openapi.yaml/components/schemas/Widget'
    description: Include Widgets in your API today!

但在生成的代码中，正在创建的是：

  @JsonProperty("widget")
  private Object widget; // expecting: `private Widget widget;`

而一个单独的类是使用以下命令创建的：

@Generated(value = "org.openapitools.codegen.languages.SpringCodegen")
public enum Widget {
  
  WIDGET("WIDGET"),
  
  private String value;

  Association(String value) {
    this.value = value;
  }

  @JsonValue
  public String getValue() {
    return value;
  }
...

如何跨文件创建对枚举定义的引用？

Answer 1

正确的语法是

  widget:
    $ref: '../openapi.yaml#/components/schemas/Widget'

也就是说，在属性定义中不需要架构关键字。此外，# 在文件名之后，而不是在文件名之前。

文件名(<代码>../openapi.yaml)仅在模式位于单独的文件中时才需要。如果< code>Widget模式与POST/PUT请求定义在同一个文件中，则不需要文件名:

  widget:
    $ref: '#/components/schemas/Widget'

如果您想在＜code＞$ref，则需要将＜code＞$ref＜/code＞包装为＜code＞allOf＜/code＞（如下所述）：

  widget:
    allOf:
      - $ref: '#/components/schemas/Widget'
    description: Include Widgets in your API today!