08-openapi

08 · OpenAPI

Generating an OpenAPI document and browsing it in a docs UI, straight from route schemas.

What it demonstrates

• OpenAPIModule.forRoot() with API info
• Route schemas doubling as API documentation — no separate spec to maintain
• summary and description on each route
• describe() for field-level docs and named() for reusable components
• Versioned paths appearing in the generated document

Run it

npm install
npm run dev

Try it

The JSON document:

curl http://localhost:8787/api/openapi.json

openapi  3.0.0
info     {"title": "Users API", "version": "1.0.0", ...}
paths    ['/api/v1/users', '/api/v1/users/{id}']

User is emitted once and referenced everywhere it appears:

{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/User"}}},"required":["data"],"additionalProperties":false}

The docs UI:

open http://localhost:8787/api/docs

The endpoints themselves work as normal:

curl -X POST http://localhost:8787/api/v1/users \
  -H 'Content-Type: application/json' \
  -d '{"name":"Ada","email":"[email protected]"}'

role is omitted above and defaults to member.

Key files

• src/app.module.ts — OpenAPIModule.forRoot()
• src/users/users.schemas.ts — schemas with describe() and named()
• src/users/users.controller.ts — summary / description per route

Learn more

• Stratal documentation
• Stratal on GitHub
• All examples

Star Stratal

If this example helped, please star the Stratal repo — it is the simplest way to support the project and helps other developers find it.