I’m working on an OpenAPI 3.0 specification and I’m encountering a problem with the generated documentation in Swagger UI (or any similar tool). Specifically, I’m using the allOf construct to inherit properties from a GenericCategory schema into a ProductCategory schema. The ProductCategory schema has a subcategory property that is also of type GenericCategory.

Here’s a simplified version of my YAML schema:

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

The issue is that in the generated documentation, the subcategory field appears duplicated or doesn’t render as expected, leading to confusion.

What I’ve Tried:

I verified the YAML syntax, and it is valid.
Considered creating a separate Subcategory schema, but I’m concerned about maintainability and DRY (Don’t Repeat Yourself) principles.
Reviewed Swagger UI and OpenAPI documentation, but couldn’t find a clear solution.
Questions:

Is there a way to correctly render the subcategory field without duplication using allOf?
Should I create a separate schema for Subcategory, and if so, how can I do this while still adhering to DRY principles?
Are there any known configurations in Swagger UI or other tools that can flatten or better handle such schemas?
Any advice or suggestions would be greatly appreciated!