gen-openapi

Overview ¶

Command gen-openapi converts the swaggo-generated Swagger 2.0 document (docs/swagger.json) into a clean OpenAPI 3.0.3 document written to api/openapi.yaml.

This is the versioned contract other services (notably the paper CLI, which generates a Rust client with progenitor) consume. progenitor + openapiv3 are OpenAPI 3.0.x-only and require an operationId on every operation, so this tool:

• converts 2.0 -> 3.0.3 in-process via kin-openapi (no Node toolchain),
• forces the version string to 3.0.3,
• synthesizes a deterministic operationId for any operation still missing one (belt-and-suspenders: the handlers carry @ID annotations, but a future un-annotated handler must not be able to break downstream codegen),
• strips swag's package prefixes from component schema names (and rewrites every $ref) so the generated Rust types read as SessionItem rather than ApiSessionItem, with a collision guard that keeps the qualified name when two packages would otherwise collapse onto the same bare name.

Run via `make openapi` (which runs `make swag` first). Do not edit the output by hand.