OpenAPI v3多层鉴别器多态模型在Redocly中无法正常渲染的问题咨询

Hey there, looking at your OpenAPI v3 definition, the issue isn't that you're violating the spec (since it passes Redocly's linter), but rather a structural inconsistency in how your Dog polymorphic hierarchy is set up that throws off Redocly's rendering engine. Let's break this down and fix it:

Root Causes #

1. Dog schema doesn't inherit from Pet
   Your Dog schema uses oneOf to reference LargeDog and SmallDog, but it doesn't explicitly inherit the base Pet properties. Since both sub-types do inherit from Pet, this creates a disconnected hierarchy that Redocly struggles to parse for rendering.

2. Redundant type field in SmallDog
   SmallDog repeats the type property that's already defined in the parent Dog schema. This duplication can confuse the discriminator logic and disrupt rendering.

3. Implicit inheritance gaps
   While your discriminator mappings are technically correct, combining them with explicit allOf inheritance helps Redocly better understand the model hierarchy.

Fixed OpenAPI Definition #

Here's the corrected version that will render properly in Redocly:

openapi: 3.0.3
info:
  version: 0.0.3-SNAPSHOT
  title: Pet Adaption API
  description: |
    Adopt a pet!
servers:
  - url: 'https://example/pet/api/v1'
    description: Pet Adaption API
paths:
  /pet_adaptions:
    post:
      summary: Mark a pet for adaption
      description: Mark a pet for adaption
      operationId: adopt
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PetType'
        required: true
      responses:
        200:
          description: The pet was marked for adaption
        400:
          description: The payload was poorly formatted.
        500:
          description: Unexpected server error.
components:
  schemas:
    Pet:
      type: object
      required:
        - name
      properties:
        name:
          type: string
          description: What goes on their collar.
    PetType:
      type: object
      oneOf:
        - $ref: '#/components/schemas/Cat'
        - $ref: '#/components/schemas/Dog'
      discriminator:
        propertyName: type
        mapping:
          CAT: '#/components/schemas/Cat'
          DOG: '#/components/schemas/Dog'
    Dog:
      type: object
      allOf:
        - $ref: '#/components/schemas/Pet'
      oneOf:
        - $ref: '#/components/schemas/LargeDog'
        - $ref: '#/components/schemas/SmallDog'
      discriminator:
        propertyName: size
        mapping:
          large: '#/components/schemas/LargeDog'
          small: '#/components/schemas/SmallDog'
      required:
        - type
      properties:
        type:
          type: string
          description: The type of pet. Always set to `DOG`
    LargeDog:
      type: object
      required:
        - size
        - floofFactor
      properties:
        size:
          type: string
          description: The size of dog. Always set to `large`
        floofFactor:
          type: integer
          description: Floofiness of large dog (1 - 10)
    SmallDog:
      type: object
      required:
        - size
        - yapFactor
      properties:
        size:
          type: string
          description: The size of dog. Always set to `small`
        yapFactor:
          type: number
          description: Yapiness of small dog (0 - 1.0)
    Cat:
      type: object
      allOf:
        - $ref: '#/components/schemas/Pet'
      required:
        - type
        - colour
      properties:
        type:
          type: string
          description: The type of pet. Always set to `CAT`
        colour:
          type: string
          description: Colour of the cat's coat

Key Adjustments Explained #

• Added allOf inheritance to Dog: Now Dog explicitly inherits from Pet, matching how Cat is structured. This gives Redocly a clear hierarchy to follow when rendering the model and its sub-types.
• Removed redundant type from SmallDog: Since type is already defined in the parent Dog schema, repeating it was unnecessary and caused confusion.
• Simplified sub-type schemas: LargeDog and SmallDog no longer need to reference Pet directly, as their parent Dog already handles that. This creates a cleaner, nested polymorphic structure.

After these changes, Redocly should correctly render all your valid examples (LargeDog, SmallDog, Cat) in the API documentation, while still passing the linter checks.

内容的提问来源于stack exchange，提问作者user5860663