Skip to content

fix(api): propagate flat-schema hoisting option across spec output APIs #378

Description

@yeongseon

Context

#377 (v0.20.0-unreleased) added the opt-in hoist_flat_schemas: bool = False parameter, but only on generate_openapi_spec(). The sibling public output APIs do not expose or forward it, so the feature is unreachable through the documented surface:

  • get_openapi_json()spec.py:678 (no hoist_flat_schemas, does not forward)
  • get_openapi_yaml()spec.py:724 (same)
  • generate_openapi_report()spec.py:902 (same)

Worse, generate_openapi_report()'s docstring at spec.py:920 still states "Parameters mirror generate_openapi_spec." — which is now inaccurate.

Result: generate_openapi_spec(hoist_flat_schemas=True) works, but get_openapi_json(hoist_flat_schemas=True) / get_openapi_yaml(...) / generate_openapi_report(...) raise TypeError.

Target release: next OpenAPI minor (pre-release cleanup for the flat-hoist feature).

Acceptance Checklist

  • Add hoist_flat_schemas: bool = False to get_openapi_json, get_openapi_yaml, and generate_openapi_report, forwarding it to generate_openapi_spec.
  • Fix the generate_openapi_report docstring so the "mirrors" statement stays accurate (or enumerate the shared params explicitly).
  • Tests: each wrapper produces hoisted components.schemas when hoist_flat_schemas=True and preserves current shape when False.
  • Coverage stays >= 95%.

Out of scope

  • A CLI --hoist-flat-schemas flag (optional; track separately if desired). If kept Python-only, document it as an advanced option.

References

Metadata

Metadata

Assignees

No one assigned

    Labels

    bugSomething isn't workingpriority:p2Normal / later

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions