feat: auto-generate OpenAPI spec from route schemas#154
Conversation
Replace manual gateway/openapi.yaml with @fastify/swagger auto-generation. All 10 routes now have inline JSON Schema definitions that Fastify uses for both response validation and OpenAPI spec generation. - Add @fastify/swagger + @fastify/swagger-ui dependencies - Extract reusable schemas into gateway/schemas.mjs - Add inline schema to all gateway and peer routes - Serve Swagger UI at /docs and JSON spec at /docs/json - Remove hand-maintained openapi.yaml - Update Dockerfile to include schemas.mjs - Add /docs/json spec test
Jing-yilin
left a comment
Jing-yilin
left a comment
There was a problem hiding this comment.
-
gateway/server.mjs:611,gateway/server.mjs:656,gateway/server.mjs:692
The new POST route schemas only declareresponse, so the generated/docs/jsonspec no longer includes anyrequestBodyfor/peer/announce,/peer/heartbeat, or/peer/message. That is a regression from the deletedgateway/openapi.yaml, and it makes the auto-generated spec incomplete for anyone trying to call those endpoints from the docs alone. I verified this locally by injecting/docs/json: all three operations currently haverequestBody === undefinedeven thoughAnnounceRequest,HeartbeatRequest, andSignedMessageare registered ingateway/schemas.mjs. -
test/gateway-worlds.test.mjs:70
The new docs test only checks that the paths and component schema names exist, so it still passes when the POST operations lose their request contracts entirely. Since this PR replaces the hand-maintained OpenAPI file, the test should assert that those three operations actually reference their request schemas.
Add body schema refs for /peer/announce, /peer/heartbeat, /peer/message so the auto-generated OpenAPI spec includes requestBody documentation. Disable body validation in the peer plugin scope to avoid interfering with the custom rawBody content parser used for signature verification. Add test assertion that POST operations reference their request schemas.
1 participant
Stacked on #153
Replace the hand-maintained
gateway/openapi.yamlwith@fastify/swaggerauto-generation from route schemas.Changes
@fastify/swagger+@fastify/swagger-uiin the gatewaygateway/schemas.mjsschemato all 10 gateway routes (health, agents, worlds, world/:id, agent.json, peer/ping, peer/peers, peer/announce, peer/heartbeat, peer/message)GET /docsand JSON spec atGET /docs/jsongateway/openapi.yaml(no longer needed)schemas.mjsBenefits
/docsprovides interactive API explorer for development