Migrate OpenAPI spec from Swagger 2.0 to OpenAPI 3 — unlocks bearer HTTP scheme in Swagger UI

[SyniRon]

This was generated by AI during triage.

Background

This issue started life as a Swagger-UI usability complaint: the OpenAPI security scheme is declared type: apiKey, so Swagger UI's Authorize dialog does not auto-prepend Bearer . Users paste their raw cav7_… key, the gateway sees Authorization: cav7_…, fails the Bearer prefix check, and returns a generic 401 with no hint as to why. That has already cost real support time.

The 401-message half of that pain is being addressed in #99 — small, agent-tractable, ships independently.

The security-scheme half runs into a spec-version constraint that warrants reframing this ticket. The OpenAPI-3 fix the original report proposed (type: http, scheme: bearer) is not expressible in Swagger 2.0, which is what grpc-gateway's protoc-gen-openapiv2 emits. The valid Swagger-2.0 SecurityScheme.Type values are BASIC, API_KEY, OAUTH2 — there is no HTTP. Fixing the scheme cleanly therefore requires moving the generated spec to OpenAPI 3.

Capturing this here as the umbrella migration ticket so the design call is tracked rather than lost.

Scope

• Produce (or convert to) an OpenAPI 3 spec from the existing .proto definitions and ship it as the canonical embedded asset.
• Replace the apiKey security scheme with type: http, scheme: bearer so Swagger UI auto-prepends Bearer and users paste only the raw key.
• Keep milpacs.proto and tickets.proto in sync — both currently declare the same bearer apiKey scheme.
• Update the embedded Swagger UI distribution to a version that renders the new spec cleanly.

Implementation options to evaluate

1. gnostic / gnostic-grpc post-conversion — keep grpc-gateway's openapiv2 output as an intermediate, convert to OpenAPI 3 before embed. Lowest change to the proto-generation pipeline.
2. A different / newer grpc-gateway plugin that emits OpenAPI 3 directly — community options exist; needs research for maturity, behavioral parity, and active maintenance.
3. Hand-maintained OpenAPI 3 spec alongside the proto-generated one — strictly worse; listed only for completeness.

Constraints

• The OpenAPI assets ship inside the binary via //go:embed openapi/assets/..., so whichever path is picked has to fit that build pipeline.
• The release workflow sed-substitutes the GitHub tag into proto/milpacs.proto and proto/tickets.proto before make generate. The version-baking behavior must survive the migration.
• Known external consumers (7cav-cavbot2, 7cav-adr) speak the JSON gateway directly, not OpenAPI-driven clients — so the spec-format change is low-blast-radius for clients today and primarily improves the in-browser Swagger UI experience and any future tooling.

Why this is ready-for-human, not ready-for-agent

• Picking between gnostic conversion, a different generator, or a hand-maintained spec is a design call.
• The downstream Swagger UI bundle pairing (versions of swagger-ui*.js under openapi/assets/) needs a human picking the right UI version and verifying it renders correctly with the new spec.

Related

• auth: 401 message should hint at expected "Bearer <key>" scheme #99 — ready-for-agent ticket for the two-tier 401-message improvement (covers the user-facing pain in the meantime).
• Companion ApiKeyManager addon-side ticket covering new-key-page usage instructions.