Hacktoberfest 2026 : les issues que les mainteneurs ont marquées pour octobre, ouvertes et accessibles aux débutants. Parcourir les issues Hacktoberfest

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

Ouverte
  • Quelque chose ne va pas ?
#1,411 0 commentaires 0 réactions 0 personnes assignées Voir sur GitHub

Personne n'a encore pris cette issue.

Évaluation

Difficulté
3/5
Temps estimé
1-2 jours
Accessibilité débutants
55/100
Type d'issue
Bug
Clarté
Plutôt claire
Activité
À l'abandon
Stack technique
openapi, python
Domaine
api, tooling

Piste de recherche

Aucun fichier source ni test n’est indiqué dans l’issue. Commencez par générer un client Python à partir du repro OpenAPI 3.1 fourni et examinez la documentation des arguments de la méthode générée. Le travail est considéré comme terminé lorsque parameter.description est utilisé pour la documentation des arguments, tandis que les descriptions du schéma restent disponibles pour les détails concernant le type ou le format de la valeur.

Rédigé par le modèle d'indexation à partir du texte de l'issue.

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!

Langage dominant
Python
Étoiles
2k
Forks
296
Merge moyen
34 min
PR mergées (30 j)
1

Préparer son environnement

Par où commencer

  1. Lisez l'issue en entier, puis le guide de contribution du projet.
  2. Signalez en commentaire que vous la prenez — cela évite que deux personnes fassent le même travail.
  3. Forkez le dépôt et travaillez sur une branche.
  4. Ouvrez une pull request qui référence le numéro de l'issue.

Autres issues de openapi-generators/openapi-python-client

Toutes les issues de openapi-generators/openapi-python-client

Issues similaires

Plus d'issues Python

Recevez les nouvelles issues par e-mail

Un résumé court des issues GitHub adaptées aux débutants.