Duplicate description on empty additionalProperties

[Devon-White]

Describe the Bug

When a property is defined as an object with additionalProperties and no properties are defined, the description is duplicated at both the top-level object and the additionalProperties level.

This does not occur in the following scenarios:

1. When a description is provided at both the top level and additionalProperties.

   • Example workaround:

     workaround:
       allOf:
         - $ref: '#/components/schemas/WorkAroundModel'
       description: Workaround

     And the ref:

     WorkAroundModel:
       type: object
       additionalProperties: {}
       description: Workaround

This workaround forces the object to render without a additionalProperties (property name*), though it’s not ideal. We cannot omit additionalProperties due to the need for valid examples in TypeSpec.

2. When additionalProperties contains valid properties, the duplication does not occur.

Expected Behavior

The description should not be duplicated. The additionalProperties section should either stay empty or have a preset description explaining that the property name is user-defined.

Current Behavior

The top-level object description is duplicated at the additionalProperties level when additionalProperties is empty.

Possible Solutions

1. Create a separate ref:

   • As outlined above, you can use a ref to handle the empty additionalProperties object and providing it a description.

2. Skip additionalProperties:

   • Omitting additionalProperties altogether would resolve the issue, but since we are using TypeSpec, we need the type to align for the examples. Additionally, this wouldn't be 100% accurate to the API.

3. Fix in the generator:

   • Ideally, a fix for the doc generator should account for this.

Steps to Reproduce

Test schema:

openapi: 3.0.0
info:
  title: Bug Test
  description: Testing Bug
  version: 0.0.0
tags:
  - name: Test
paths:
  /with-bug:
    post:
      operationId: TestBug_create
      summary: With Bug
      description: |-
        This is to test an `additionalProperties` bug.
      responses:
        '201':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ReturnType'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/WithBug'
components:
  schemas:
    ReturnType:
      type: object
      required: [test1, test2]
      properties:
        test1:
          type: string
          enum: [Yes]
        test2:
          type: string
          enum: [Test]
    WithBug:
      type: object
      required: [with_bug, workaround, workaround_with_bug, additional_props_without_bug]
      properties:
        with_bug:
          type: object
          additionalProperties: {}
          description: Bug with additionalProperties
        workaround:
          allOf:
            - $ref: '#/components/schemas/WorkAroundModel'
          description: Workaround
        workaround_with_bug:
          $ref: '#/components/schemas/WorkAroundModel'
        additional_props_without_bug:
          type: object
          additionalProperties:
            type: object
            properties:
              test3:
                type: string
                enum: [Additional Prop Test]
          description: Test with additional props
    WorkAroundModel:
      type: object
      additionalProperties: {}
      description: Workaround

1. Generate documentation from this schema.
2. Observe the duplicated descriptions.

Screenshots

Additional Context

Does not seem to render the duplicate description in a SWAGGER editor/viewer.

Environment

• Version: 3.0.2 & 4.0.1