Skip to content

fix: use parameter descriptions in endpoint docstrings - #1491

Open
ska2704 wants to merge 1 commit into
openapi-generators:mainfrom
ska2704:fix/parameter-descriptions
Open

ska2704 wants to merge 1 commit into
openapi-generators:mainfrom
ska2704:fix/parameter-descriptions

Conversation

@ska2704

@ska2704 ska2704 commented Oct 6, 2026

Copy link
Copy Markdown

Fixes #1411.

Generated endpoint argument docstrings now prefer non-empty Parameter Object descriptions, falling back to schema descriptions when the parameter description is missing or empty. For example, since now documents "Only include tasks changed after this timestamp" instead of only "Unix timestamp in milliseconds".

The override applies to the endpoint property after schema parsing, so reusable model and field documentation keeps its schema descriptions. Component parameter references also retain their descriptions. Functional tests cover query, path, header and cookie parameters, schema fallback, references, shared model reuse, and all four sync/async endpoint functions.

Validation on Python 3.12:

  • The new regression fails on unchanged main with four expected assertion failures.
  • Docstring functional tests: 12 passed.
  • pdm test_with_coverage: 473 passed, 100% coverage, all 5 snapshots passed.
  • pdm run ruff check ., pdm run ruff format . --check, and pdm mypy --show-error-codes: passed.
  • OPENAPI_PYTHON_CLIENT_FUZZ_EXAMPLES=100 pdm fuzz: 100 generated examples passed.

The Docker-backed live integration tests were not run locally because a container runtime is unavailable.

AI assistance: OpenAI Codex was used for investigation, implementation, automated review, and validation.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

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

1 participant