在 OpenAPI (Swagger) 中重用枚举的子集

Question

我试图实现一个 OpenAPI 定义，其中我将允许值的共享、完整列表定义为枚举，然后在不同位置使用值的子组来显示每种情况下允许哪些值。

使用Swagger.io 上枚举规范的示例，如果我有这样的定义：

paths:
  /products:
    get:
      parameters:
      - in: query
        name: color
        required: true
        schema:
          $ref: '#/components/schemas/Color'
      responses:
        '200':
          description: OK
components:
  schemas:
    Color:
      type: string
      enum:
        - black
        - white
        - red
        - green
        - blue

那么是否可以定义例如两个以颜色作为参数的不同路径，但其中一个仅接受black或white另一个接受所有颜色？

Answer 1

没有好的方法可以重用枚举的一部分。最好的方法是定义单独的枚举。

一种可能的解决方法是按照此处的建议oneOf将部分枚举“组合”到完整枚举中。但是，枚举模式可能无法在 Swagger UI 和代码生成器中用作枚举。oneOf

components:
  schemas:
    BlackOrWhite:
      type: string
      enum:
        - black
        - white
    Color:
      oneOf:
        - $ref: '#/components/schemas/BlackOrWhite'
        - type: string
          enum:
            - red
            - green
            - blue

YAML&anchors和合并键的技巧 << 不起作用，因为 YAML 仅支持映射（对象）中的合并键，而不支持序列（数组）中的合并键。

# This will NOT work in YAML

components:
  schemas:
    BlackOrWhite:
      type: string
      enum: &BLACK_WHITE
        - black
        - white
    Color:
      type: string
      enum:
        << : *BLACK_WHITE
        - red
        - green
        - blue