Skip to content

feat(spec): emit METHOD_BINDING_MISMATCH warning for explicit method vs binding #362

Description

@yeongseon

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:

  1. 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).
  2. (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

  • Add WarningCode.METHOD_BINDING_MISMATCH to _warnings.py.
  • During scan, stamp the binding method set on the entry (e.g. _binding_methods) so spec.py can cross-check without re-reading the app.
  • collect_spec_warnings() emits METHOD_BINDING_MISMATCH when an entry's explicit method is not in its binding method set (skip when binding methods are unspecified — runtime answers all).
  • Deterministic ordering preserved; tests for positive and negative cases.
  • make check-all green; coverage >= 95%.

Out of scope

  • Changing which method wins (explicit @openapi(method=) still authoritative — this only surfaces the disagreement).

References

Metadata

Metadata

Assignees

No one assigned

    Labels

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions