在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

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

- MJV

Answer 1

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

一个可能的解决办法是使用 oneOf 将部分枚举类型“组合”成完整的枚举类型，如这里建议的。然而，oneOf 枚举模式可能不会在Swagger UI和代码生成器中作为枚举类型工作。

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

- Helen

---

谢谢。这证实了我的怀疑。我尝试使用引用和锚点，但没有成功。目前我在不同路径中有单独的枚举，虽然它在技术上可以工作，但在生成的代码中path1.BLACK != path2.BLACK，这并不是最优的。但我想我必须在路径处理程序中编写一些功能来将给定的值映射到一个共享的枚举（在我自己的“手写”代码中定义）。 - MJV

您可能会对OpenAPI规范存储库中的此讨论感兴趣：https://github.com/OAI/OpenAPI-Specification/issues/1552 - Helen