Xodocs
Automating API documentation
The problem
The problem
Express API teams typically write and maintain OpenAPI/Swagger documentation by hand, separately from the validation schemas their code actually enforces. The two drift apart as endpoints change, and nobody notices until a consumer hits a mismatch.
The approach
Xodocs reads the Zod schemas and structured annotations (@route, @summary and similar tags) already present in an Express app's route handlers, and generates OpenAPI documentation from them directly — serving a Swagger UI at /docs and the raw spec as JSON.
Implementation
Implemented
- OpenAPI generation from existing Zod schemas and route annotations
- Swagger UI served at /docs, raw spec at /docs/openapi.json
- Bearer and API-key auth scheme support
- @public tag to exclude specific routes from documentation
Engineering decisions
Engineering decisions
Documentation can't drift from validation
Because the docs are generated from the same Zod schemas the API uses at runtime to validate requests, the documentation can't describe a shape the code doesn't actually enforce — the usual failure mode for hand-maintained API docs.
Results and status
Results and status
A small, real open-source tool (MIT-licensed, public npm package) rather than a widely-adopted platform — there's no meaningful download or usage count to cite, so none is claimed here.
Contributors & attribution
Contributors and attribution
Built by Elijah Soladoye.
Have a similar operational challenge?
Tell us what's happening and we'll tell you honestly whether it's something we can help with.