Hacktoberfest 2026: los issues que los mantenedores marcaron para octubre, abiertos y aptos para principiantes. Explorar issues de Hacktoberfest

Duplicate description on empty additionalProperties

Abierto
  • ¿Algo no está bien?
#966 0 comentarios 0 reacciones 0 asignados Ver en GitHub

Los mantenedores suelen responder en 2 días

Nadie ha tomado este issue todavía.

Evaluación

Dificultad
3/5
Tiempo estimado
1-2 días
Aptitud para principiantes
45/100
Tipo de issue
Error
Claridad
Bastante claro
Estado de actividad
Estancado
Stack tecnológico
openapi, typescript
Área
documentation

Línea de trabajo

Start by generating documentation from the provided OpenAPI schema and compare the empty additionalProperties case with the cases that do not duplicate descriptions. Trace the generator's schema rendering path for additionalProperties, then verify that the description appears only once and add a regression test covering the supplied schema.

Escrito por el modelo de indexación a partir del texto del issue.

Descripción

bug

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.

  1. 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

image

Additional Context

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

image

Environment

  • Version: 3.0.2 & 4.0.1
Lenguaje dominante
TypeScript
Estrellas
1.1k
Forks
317
Merge medio
1 d 14 h
PR fusionados (30 d)
17

Preparar el entorno

Primeros pasos

  1. Lee el issue completo y luego la guía de contribución del proyecto.
  2. Comenta en el issue que vas a ocuparte — evita que dos personas hagan lo mismo.
  3. Haz un fork del repositorio y trabaja en una rama.
  4. Abre un pull request que haga referencia al número del issue.

Más de PaloAltoNetworks/docusaurus-openapi-docs

Todos los issues de PaloAltoNetworks/docusaurus-openapi-docs

Issues similares

Más issues de TypeScript

Recibe los nuevos issues en tu correo

Un resumen breve de issues de GitHub para principiantes.