Stoplight Elements Doc Issue

replicate_doc_issue.yaml

openapi: 3.0.2
info:
  title: Doc Issue
  description: |-
    This OpenAPI yaml is an attempt to replicate an issue I've seen with the 
    generated documentation when a schema includes the allOf attribute.

    My goal is to have a "Base Object" schema and then a "Base Group Object" 
    schema which is a superset of the Base Object in that it has two 
    additional attributes `children` and `hydrated_children` that contain the
    ids and the full representations of other Base Objects.

    I also want to have a unique description string for the Base Group Object 
    that describes it in general.   I've found that by creating an internal 
    baseObject schema I can create public facing descriptions for the Base 
    Object and Base Group Objects.

    The Base Group Object uses the `allOf` tag to include a referece to the 
    baseObject schema and then define the additional attributes.  When the 
    baseObject schema contains a `hydrated_children` attribute, this all works 
    as I wish: see the [publicBaseGroupObject](./schemas/publicBaseGroupObject) 
    in the schemas section.

    The "bug" that I'm running into is if I remove the `hydrated_children` 
    attribute from the baseObject the documentation for the group schema no 
    longer behaves as I expect. It does not seem to respect the `allOf` 
    attribute, in that it does not show the documentation string defined as 
    part of this attribute, nor does it show the additionally defined attributes. 
    It only shows the documentation for the baseObject.   To see what I mean 
    see the 
    [publicBaseGroupObjectWithoutHydratedChildrenInBase](./schemas/publicBaseGroupObjectWithoutHydratedChildrenInBase) 
    in the schemas section
  version: '1.0'

components:
  schemas:
    # The core object to be referenced by other "public" schemas
    # This is referenced in several places so that the description can be 
    # changed depending on the context
    baseObject:
      type: object
      x-internal: true # Don't display in schemas section of docs
      additionalProperties: false
      properties:
        id:
          type: integer
          format: int64
          nullable: false
          description: A system defined unique identifier for the category.
        name:
          type: string
          nullable: false
          description: The name of the category.
          minLength: 1
          maxLength: 100
        description:
          type: string
          nullable: true
          description: The description of the category or `null` if not set.
          maxLength: 200
        hydrated_children:
          description: This will be removed
          type: number
      required:
        - id
        - name
        - description

    publicBaseObject:
      description: >
        This is the publically documented baseObject.
      allOf:
        - $ref: '#/components/schemas/baseObject'

    publicBaseGroupObject:
      description: >
        The object is a superset of the baseObject.  It includes everything
        that the publicBaseObject has, but also two additional parameters.
        We want the documentation for this object to show this description as 
        well as expanding to show the doc strings for the attributes in the 
        baseObject and extra attributes added here.
      allOf:
        - $ref: '#/components/schemas/baseObject'
        - type: object
          properties:
            children:
              type: array
              nullable: true
              description: An array that exists only in the baseGroupObject.
              items:
                type: number
            hydrated_children:
              type: array
              nullable: true
              description: Another array that exists only in the baseGroupObject this 
                is populated by the full baseObjects that are children of a 
                baseObject
              items:
                $ref: '#/components/schemas/baseObject'

    baseObjectWithoutHydratedChildren:
      type: object
      x-internal: true # Don't display in schemas section of docs
      additionalProperties: false
      properties:
        id:
          type: integer
          format: int64
          nullable: false
          description: A system defined unique identifier for the category.
        name:
          type: string
          nullable: false
          description: The name of the category.
          minLength: 1
          maxLength: 100
        description:
          type: string
          nullable: true
          description: The description of the category or `null` if not set.
          maxLength: 200
      required:
        - id
        - name
        - description

    publicBaseObjectWithoutHydratedChildren:
      description: >
        This is the publically documented baseObject.
      allOf:
        - $ref: '#/components/schemas/baseObjectWithoutHydratedChildren'

    publicBaseGroupObjectWithoutHydratedChildrenInBase:
      description: >
        The object is a superset of the baseObject.  It includes everything
        that the publicBaseObject has, but also two additional parameters.
        We want the documentation for this object to show this description as 
        well as expanding to show the doc strings for the attributes in the 
        baseObject and extra attributes added here.
      allOf:
        - $ref: '#/components/schemas/baseObjectWithoutHydratedChildren'
        - type: object
          properties:
            children:
              type: array
              nullable: true
              description: An array that exists only in the baseGroupObject.
              items:
                type: number
            hydrated_children:
              type: array
              nullable: true
              description: Another array that exists only in the baseGroupObject this 
                is populated by the full baseObjects that are children of a 
                baseObject
              items:
                $ref: '#/components/schemas/baseObject'

paths:
  /endpoint:
    get:
      operationId: getEndpoint
      responses:
        '200':
          description: Minimal stuff for valid OpenAPI spec
          content:
            application/json:
              schema:
                type: object
                properties:
                  foo:
                    type: string