openapi-generators / openapi-generators/openapi-python-client
Parameter-level descriptions are ignored in Python SDK generation; only schema descriptions are used
還沒有人認領這個 Issue。
- 主要語言
- Python
- 星號
- 2k
- 分支
- 293
- 平均合併
- 34 分鐘
- 30 天內合併 PR
- 1
描述
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!
貢獻指南
從這裡開始
- 先讀完整個 Issue,再讀專案的貢獻指南。
- 在 Issue 下留言說明你要接手 —— 這能避免兩個人做同樣的事。
- Fork 儲存庫,在一個分支上完成修改。
- 送出 Pull Request,並在描述裡引用這個 Issue 編號。
研究方向
issue 中沒有指定來源檔案或測試。首先,根據提供的 OpenAPI 3.1 repro 產生 Python 用戶端,並檢查產生方法的引數文件。完成標準是使用 parameter.description 作為引數文件,同時保留 schema 描述,以提供型別或值格式的詳細資訊。
由索引模型根據 Issue 內容生成。
評估
- 技術堆疊
- openapi, python
- 領域
- api, tooling
- Issue 類型
- 缺陷
- 難度
- 3/5
- 預估耗時
- 1-2 天
- 活躍度
- 停滯
- 描述清晰度
- 基本清楚
- 新手友好度
- 55/100