OpenAPI: derive parameters from the full binding chain, plus a shape-test harness (GH-3380)

[jeremydmiller]

Fixes #3380

What was actually wrong (and what wasn't)

Being straight about the repro first: the literal parameters: [] symptom in the issue does not reproduce on main (6.17.2). CreateApiDescription has always looped RoutePattern.Parameters, so a route token is emitted no matter which method binds it. I reproduced every reported shape — compound LoadAsync binding both ids (with a service + CancellationToken), kebab-case {order-id:long} + [FromRoute(Name = ...)], [AsParameters] + LoadAsync combinations — against both OpenAPI stacks (Swashbuckle and Microsoft.AspNetCore.OpenApi), and the path parameters were present and correctly typed in all of them. My best guess is the reporter's document predates the GH-3374 fix (their host wasn't starting) — but I could not confirm it.

What the investigation did turn up is the real version of the root cause the issue describes — the API description was derived from the endpoint method signature plus its own resolved binding variables, not from the full chain:

1. Query string / header values bound only by an After/Finally postprocessor were omitted from the operation entirely. This is a genuine, reproducing bug (the new query_values_bound_only_by_a_postprocessor_are_declared test fails on main).
2. Route parameter types were read off resolved binding variables, so they degraded to the route constraint (or string) whenever the description was assembled before those frames were resolved. ASP.NET Core caches the first ApiExplorer read, and that read can happen long before codegen (build-time OpenAPI generation, the openapi command, monitoring snapshots).

The fix

HttpChain.CreateApiDescription now walks every MethodCall in the chain — the endpoint method, all middleware (compound handler Load/LoadAsync/Before, attribute- and policy-applied middleware) and all postprocessors — plus their [AsParameters] container members:

• Every RoutePattern parameter is declared as a required path parameter, with its type resolved in order: resolved route variable → the binding chain (honoring [FromRoute(Name = "order-id")], ignoring name collisions with non-bindable types like services) → the route constraint ({id:guid}) → string. That is the non-negotiable floor, now structurally guaranteed rather than dependent on codegen having run.
• [FromQuery] / [FromHeader] arguments anywhere in the chain are declared, deduplicated by name + binding source.

The shape-test harness (the actual gap)

There were essentially no assertions on the rendered document's parameters/requestBody. Now there are, on both stacks:

1. src/Http/Wolverine.Http.Tests/openapi_shape_tests.cs — Microsoft.AspNetCore.OpenApi. Renders the real OpenAPI document (same path the openapi command uses, no host start, no database) for a host pinned to the infrastructure-free Wolverine.Http.Tests.DifferentAssembly, and asserts on it via ParametersFor(path, method) / HasRequestBody(...) / RequestBodyPropertiesFor(...).

To add a shape: add an endpoint to Wolverine.Http.Tests.DifferentAssembly/OpenApiShapeEndpoints.cs, then add a [Fact] using those helpers.

Covered today: compound-handler-only route bindings (the #3380 case), an unconstrained route token typed purely from the binding chain, a renamed [FromRoute(Name = ...)] compound binding, compound-handler-only query + header, postprocessor-only query, plain handler-signature route + query, a request body alongside a compound route binding, a route value nothing binds (floor → required string), [AsParameters] route + query, and an [AsParameters] container sharing a route value with a compound handler (declared exactly once).

2. WolverineWebApi Expect* attributes — Swashbuckle. Folded into the existing GH-3135 harness (open_api_generation.verify_open_api_expectations) rather than duplicated. Added [ExpectParameterCount] (so [ExpectParameter] can't miss a phantom/duplicate parameter) and ExpectParameter.Required, plus CompoundHandlerOpenApiEndpoints.cs with the #3380 shapes.

To add a shape: annotate an endpoint method in WolverineWebApi with the Expect* attributes. No test code required — the theory picks it up automatically.

Known gap (not fixed here)

Route ids bound only by a Marten aggregate frame on an unconstrained route (e.g. [AggregateHandler] [WolverinePost("/orders/{id}/confirm")]) still render as string rather than uuid — that binding is decided during codegen, after the description is cached, and the id type is Marten-domain knowledge that Wolverine.Http can't infer from the method signatures. Worth a follow-up issue.

Tests

• Wolverine.Http.Tests: 857 passed, 0 failed, 10 skipped (net9.0)
• Wolverine.Http.AspVersioning.Tests: 66 passed (net10.0)
• dotnet build wolverine.slnx -c Release: succeeded

🤖 Generated with Claude Code