Parameter-level descriptions are ignored in Python SDK generation; only schema descriptions are used
Nobody has claimed this yet.
Assessment
- Difficulty
- 3/5
- Estimated time
- 1-2 days
- Newbie friendliness
- 55/100
Research direction
No source file or test is named in the issue. Start by generating a Python client from the provided OpenAPI 3.1 repro and inspect the generated method argument documentation. Done means parameter.description is used for the argument docs while schema descriptions remain available for type or value-format details.
Written by the indexing model from the issue text.
Description
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!
- Dominant language
- Python
- Stars
- 2k
- Forks
- 293
- Avg merge
- 34m
- Merged PRs (30d)
- 1
Contributor guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
More from openapi-generators/openapi-python-client
-
Difficulty 2/5 1-3 hours Newbie friendliness 68/100
-
Difficulty 2/5 1-3 hours Newbie friendliness 65/100
-
Difficulty 3/5 1-2 days Newbie friendliness 72/100
openapi-generators/openapi-python-client#1451 · 1 comment ·
-
Difficulty 3/5 1-2 days Newbie friendliness 52/100
-
Difficulty 3/5 1-2 days Newbie friendliness 64/100
openapi-generators/openapi-python-client#1435 · 1 comment ·
All issues in openapi-generators/openapi-python-client
Similar issues
-
essnmx good first issue
Difficulty 1/5 Under an hour Newbie friendliness 95/100
-
[Feature] 奇物选择添加优先级 Open
Difficulty 2/5 1-3 hours Newbie friendliness 65/100
syfoud/Simulated_Scepter#174 ·
-
Difficulty 2/5 1-3 hours Newbie friendliness 75/100
Giskard-AI/giskard-oss#2840 · 1 comment ·
-
A claim comment carrying the issue number is silently declined while the workflow reports success Openarea: repo bug perceived difficulty: 2
Difficulty 2/5 1-3 hours Newbie friendliness 70/100
-
Difficulty 2/5 1-3 hours Newbie friendliness 75/100
yeti-platform/yeti#1380 ·