Context
Follow-up to #358/#359. When @openapi is decorated below @app.route, the binding is the runtime source of truth for method/route, but the generated spec can silently disagree with no signal. collect_spec_warnings() currently returns () even when the spec method contradicts the binding. Two cases warrant a structured warning:
- Explicit mismatch:
@openapi(method="put") on a handler whose binding is methods=["POST"]. Today the decorator's explicit method wins and the spec emits a PUT /things operation that the runtime does not serve. This nonexistent-operation case should warn (it is a genuine authoring error, distinct from documenting a subset of a multi-method binding).
- (Optional, informational) Unresolved collapse before the plain-
@openapi fix lands: binding POST but spec emits GET. Becomes moot once that fix ships.
Do not warn for normal inference (method=None resolved from the binding).
Acceptance Checklist
Out of scope
- Changing which method wins (explicit
@openapi(method=) still authoritative — this only surfaces the disagreement).
References
Context
Follow-up to #358/#359. When
@openapiis decorated below@app.route, the binding is the runtime source of truth for method/route, but the generated spec can silently disagree with no signal.collect_spec_warnings()currently returns()even when the spec method contradicts the binding. Two cases warrant a structured warning:@openapi(method="put")on a handler whose binding ismethods=["POST"]. Today the decorator's explicit method wins and the spec emits aPUT /thingsoperation that the runtime does not serve. This nonexistent-operation case should warn (it is a genuine authoring error, distinct from documenting a subset of a multi-method binding).@openapifix lands: bindingPOSTbut spec emitsGET. Becomes moot once that fix ships.Do not warn for normal inference (method=None resolved from the binding).
Acceptance Checklist
WarningCode.METHOD_BINDING_MISMATCHto_warnings.py._binding_methods) sospec.pycan cross-check without re-reading the app.collect_spec_warnings()emitsMETHOD_BINDING_MISMATCHwhen an entry's explicitmethodis not in its binding method set (skip when binding methods are unspecified — runtime answers all).make check-allgreen; coverage >= 95%.Out of scope
@openapi(method=)still authoritative — this only surfaces the disagreement).References
src/azure_functions_openapi/_warnings.py,spec.py::collect_spec_warnings.