openapi-generators / openapi-generators/openapi-python-client
Parameter-level descriptions are ignored in Python SDK generation; only schema descriptions are used
Nessuno ha ancora preso questa issue.
- Lingua principale
- Python
- Stelle
- 2k
- Fork
- 293
- Merge medio
- 34m
- PR unite (30g)
- 1
Descrizione
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!
Guida per i contributori
Apri la guida per i contributori
Come iniziare
- Leggi tutta la issue e poi la guida ai contributi del progetto.
- Commenta sulla issue per dire che te ne occupi tu — evita che due persone facciano lo stesso lavoro.
- Fai un fork del repository e lavora su un branch.
- Apri una pull request che faccia riferimento al numero della issue.
Direzione di ricerca
Nell'issue non sono indicati né un file sorgente né un test. Inizia generando un client Python dal repro OpenAPI 3.1 fornito e ispeziona la documentazione degli argomenti del metodo generato. Il lavoro è completato quando parameter.description viene usato per la documentazione degli argomenti, mentre le descrizioni dello schema rimangono disponibili per i dettagli sul tipo o sul formato del valore.
Scritto dal modello di indicizzazione a partire dal testo della issue.
Valutazione
- Stack tecnologico
- openapi, python
- Ambito
- api, tooling
- Tipo di issue
- Bug
- Difficoltà
- 3/5
- Tempo stimato
- 1-2 giorni
- Stato di attività
- Ferma
- Chiarezza
- Abbastanza chiara
- Idoneità per principianti
- 55/100