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
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
Context
#377(v0.20.0-unreleased) added the opt-inhoist_flat_schemas: bool = Falseparameter, but only ongenerate_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(nohoist_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 atspec.py:920still states "Parameters mirrorgenerate_openapi_spec." — which is now inaccurate.Result:
generate_openapi_spec(hoist_flat_schemas=True)works, butget_openapi_json(hoist_flat_schemas=True)/get_openapi_yaml(...)/generate_openapi_report(...)raiseTypeError.Target release: next OpenAPI minor (pre-release cleanup for the flat-hoist feature).
Acceptance Checklist
hoist_flat_schemas: bool = Falsetoget_openapi_json,get_openapi_yaml, andgenerate_openapi_report, forwarding it togenerate_openapi_spec.generate_openapi_reportdocstring so the "mirrors" statement stays accurate (or enumerate the shared params explicitly).components.schemaswhenhoist_flat_schemas=Trueand preserves current shape whenFalse.Out of scope
--hoist-flat-schemasflag (optional; track separately if desired). If kept Python-only, document it as an advanced option.References
src/azure_functions_openapi/spec.pylines 252, 678, 724, 902, 920