0

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! Swagger UI Render Issue - subcategory Duplication with allOf

1 Answer 1

0

subcategory should also be an array entry. You are missing the - and your indentation is incorrect.


components:
  schemas:
    ProductCategory:
      allOf:
        - $ref: '#/components/schemas/GenericCategory'
        - properties:
            subcategory:
              $ref: '#/components/schemas/GenericCategory'
          required:
            - subcategory
Sign up to request clarification or add additional context in comments.

Comments

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service and acknowledge you have read our privacy policy.

Start asking to get answers

Find the answer to your question by asking.

Ask question

Explore related questions

See similar questions with these tags.