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

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

未关闭
#1,411 0 条评论 0 个 reaction 已指派 0 人 在 GitHub 查看

还没有人认领这个 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!

贡献指南

打开贡献指南

从这里开始

  1. 先读完整个 Issue,再读项目的贡献指南。
  2. 在 Issue 下留言说明你要接手 —— 这能避免两个人做同样的事。
  3. Fork 仓库,在一个分支上完成修改。
  4. 提交 Pull Request,并在描述里引用这个 Issue 编号。

调研方向

issue 中没有指定源文件或测试。首先,根据提供的 OpenAPI 3.1 repro 生成 Python 客户端,并检查生成方法的参数文档。完成标准是使用 parameter.description 作为参数文档,同时保留 schema 描述,以提供类型或值格式的详细信息。

由索引模型根据 Issue 内容生成。

评估

技术栈
openapi, python
领域
api, tooling
Issue 类型
缺陷
难度
3/5
预计耗时
1-2 天
活跃度
停滞
描述清晰度
基本清楚
新手友好度
55/100

把新 issue 发到你的邮箱

精选适合新手参与的 GitHub issue 摘要。