Track the OpenApi 10.x + Swashbuckle 10.x migration that unfreezes the WebApp OpenAPI hold

[wormeyman]

The WebApp OpenAPI stack is frozen at its current majors and the unlock is a real migration, not a version bump. This tracks it so the path lives somewhere actionable rather than only in a code comment. Sibling of #44, which does the same for the Verify/xunit stack.

What is frozen

Package	Installed	Where
Microsoft.AspNetCore.OpenApi	8.0.10	src/WebApp/WebApp.csproj
Swashbuckle.AspNetCore	6.9.0	src/WebApp/WebApp.csproj
swashbuckle.aspnetcore.cli	6.5.0	src/WebApp/.config/dotnet-tools.json

.github/renovate.json5 holds OpenApi at <9.0.0 and both Swashbuckle packages at <7.0.0, grouped as "WebApp OpenAPI stack" so they cannot move piecemeal.

Why

Microsoft.AspNetCore.OpenApi 9.0+ pulls Microsoft.OpenApi 2.x, whose schema model Swashbuckle 6.x cannot consume. Swashbuckle 10.x adopts 2.x as well, so OpenApi 10.x + Swashbuckle 10.x + CLI 10.x is the mutually compatible set - but getting there breaks our code directly:

• Models/RequireNonNullablePropertiesSchemaFilter.cs uses OpenApiSchema.Nullable, which is removed (OpenAPI 3.1 expresses nullability differently).
• Models/OilFieldPlanRequestDefaultsSchemaFilter.cs is built on the whole Microsoft.OpenApi.Any namespace (OpenApiString/Integer/Double/Array/Object, IOpenApiAny), which is gone in 2.x. Examples and defaults move to System.Text.Json JsonNode. That filter needs a full rewrite.

It would also regenerate the committed swagger.json (likely 3.0 -> 3.1) and, in turn, the Vue TS client in src/vue/src/lib via npm run swagger-gen.

The CLI is part of this, and is easy to miss

swashbuckle.aspnetcore.cli lives in the dotnet-tools manifest, not in any .csproj. It is what WebApp.csproj's PostBuild target runs to generate swagger.json. Renovate proposed jumping it straight to v10 on its first run, independently of the library - see #43, which closed that gap. All three move together or not at all.

Why 7.x/8.x are not a shortcut

The ceiling on the Swashbuckle packages is <7.0.0 rather than <9.0.0 because nothing establishes that 7.x or 8.x is safe against Microsoft.AspNetCore.OpenApi 8.0.x. The csproj rationale reasons about 6.x (what runs) and 10.x (the target) only. Unexamined is not the same as safe. If someone does examine an intermediate version and it holds up, that is a legitimate way to close part of this - but it needs the examination first.

Not urgent

src/WebApp is no longer deployed - the Vue front-end plans in-browser via WASM and does not call a hosted API. The API is kept for local use and for generating swagger.json. So the migration's cost/risk is not justified right now.

Revisit if: the API is hosted again, the OpenAPI contract needs to change, or a security advisory lands on one of the three packages. Any of those flips the calculation.

References

• Full rationale: src/WebApp/WebApp.csproj:19-43
• Holds: .github/renovate.json5, the two "WebApp OpenAPI stack" rules
• CLI gap that exposed the third package: Close the swashbuckle.aspnetcore.cli gap in the OpenAPI hold #43
• Dependency dashboard: Dependency dashboard #41