Swagger UI 中 allOf 的 OpenAPI 文档重复问题

Question

我正在制定 OpenAPI 3.0 规范，并且在 Swagger UI（或任何类似工具）中生成的文档遇到问题。具体来说，我使用 allOf 构造将属性从 GenericCategory 架构继承到 ProductCategory 架构。 ProductCategory 架构有一个子类别属性，该属性也是 GenericCategory 类型。

这是我的 YAML 架构的简化版本：

components:
  schemas:
    GenericCategory:
      type: object
      properties:
        id:
          type: integer
        name:
          type: string
        description:
          type: string
        path:
          type: string
        code:
          type: string
        createdAt:
          type: string
          format: date-time
      required:
        - id
        - name
        - description
        - code
        - path
        - createdAt

    ProductCategory:
      type: object
      allOf:
        - $ref: '#/components/schemas/GenericCategory'
      properties:
        subcategory:
          $ref: '#/components/schemas/GenericCategory'
      required:
        - subcategory

问题在于，在生成的文档中，子类别字段出现重复或未按预期呈现，从而导致混乱。

我尝试过的：

我验证了YAML语法，它是有效的。 考虑创建一个单独的子类别模式，但我担心可维护性和 DRY（不要重复自己）原则。 查看了 Swagger UI 和 OpenAPI 文档，但找不到明确的解决方案。 问题：

有没有办法使用 allOf 正确渲染子类别字段而不重复？ 我是否应该为子类别创建一个单独的架构？如果是，我该如何在仍然遵守 DRY 原则的情况下做到这一点？ Swagger UI 或其他工具中是否有任何已知的配置可以扁平化或更好地处理此类模式？ 任何意见或建议将不胜感激！

Answer 1

subcategory

也应该是一个数组条目。您缺少

-

并且您的缩进不正确。

components:
  schemas:
    ProductCategory:
      allOf:
        - $ref: '#/components/schemas/GenericCategory'
        - properties:
            subcategory:
              $ref: '#/components/schemas/GenericCategory'
          required:
            - subcategory