openapi-generators / openapi-generators/openapi-python-client

Parameter-level descriptions are ignored in Python SDK generation; only schema descriptions are used

Abierto
#1,411 0 comentarios 0 reacciones 0 asignados Ver en GitHub

Nadie ha tomado este issue todavía.

Lenguaje dominante
Python
Estrellas
2k
Forks
293
Merge medio
34 min
PR fusionados (30 d)
1

Descripción

Describe the bug
When generating a Python client, parameter documentation is taken from the parameter schema’s description, while the parameter object’s top-level description is ignored or not preferred.

OpenAPI defines description on the Parameter Object (“A brief description of the parameter…”) and separately allows description on schemas via the Schema Object / JSON Schema annotation model. These fields describe different layers of the API, but the current Python generation appears to only use the schema-level description for parameter docs. 

OpenAPI Spec File

openapi: 3.1.0
info:
  title: Description precedence repro
  version: 1.0.0

paths:
  /tasks/export:
    get:
      operationId: export_tasks
      summary: Export tasks
      parameters:
        - in: query
          name: since
          required: false
          description: Only include tasks changed after this timestamp.
          schema:
            type: integer
            format: int64
            description: Unix timestamp in milliseconds.
      responses:
        "200":
          description: OK

Desktop (please complete the following information):

  • OS: macOS Tahoe 26.3
  • Python Version: 3.10
  • openapi-python-client version: 0.28.2

Additional context
Expected behavior:

For simple parameters, generated method argument docs should prefer parameter.description, optionally appending schema.description as secondary value-format detail.

Example desired output:

def export_tasks(self, since: int | None = None) -> Response:
    """
    Args:
        since: Only include tasks changed after this timestamp.
               Unix timestamp in milliseconds.
    """

For reusable rich schemas, the split should be:

  • method argument docs from parameter.description
  • model/type docs from schema.description
  • field docs from property description

This would preserve the distinction OpenAPI makes between operation-level parameter semantics and reusable type semantics. This seems to be true for response bodies too.

Happy to work on this myself!

Guía de contribución

Abrir la guía de contribución

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.

Línea de trabajo

En el issue no se indica ningún archivo fuente ni ninguna prueba. Empieza generando un cliente de Python a partir del repro de OpenAPI 3.1 proporcionado e inspecciona la documentación de los argumentos del método generado. Se considera completado cuando se usa parameter.description para la documentación de los argumentos, mientras que las descripciones del esquema siguen disponibles para los detalles del tipo o del formato del valor.

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

Evaluación

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

Recibe los nuevos issues en tu correo

Un resumen breve de issues de GitHub para principiantes.