@dunx/openapi

An OpenAPI 3.1 document generated from the routes an app already has, with Swagger UI or Scalar served from the same Bun.serve as everything else.

The difference from a reflection-based generator is what it reads. A route's schemas are the objects the request path validates against. Its security metadata (@Public(), @Roles()) is what its guards enforce. Both are already on the route, so the document is not a second description that can drift from the first.

Install

bun add @dunx/openapi zod

zod is a peer dependency. Route validation targets Standard Schema, so Valibot and ArkType work for validation too, but the OpenAPI document needs JSON Schema, and only zod has z.toJSONSchema. A non-zod schema validates at runtime and appears as a permissive entry in the document, with a warning at generation time.

The documentation UI is opt-in, one optional peer per subpath. Install the one you mount, or neither:

Usage

import { HttpFactory } from '@dunx/http';
import { OpenApiModule } from '@dunx/openapi';
import { SwaggerRenderer } from '@dunx/openapi/swagger';

const app = await HttpFactory.create(
  OpenApiModule.forRoot({
    title: 'Payments',
    version: '1.4.0',
    root: AppModule, // the graph to document, and the graph that gets imported
    // Omit for the document alone: no `renderer`, no page route.
    renderer: new SwaggerRenderer({ docExpansion: 'list' }),
  }),
);
app.setGlobalPrefix('api');
await app.listen(3000);
// GET /api/docs          the explorer
// GET /api/openapi.json  the document

forRootAsync takes a factory that may inject, so an app can read its title off ConfigService or contribute another library's schema.

What is here

The OpenAPI guide is canonical.

Security comes from the same @Public() and @Roles() metadata the guards read at runtime, so there is no second annotation for the document to disagree with. A response schema is documentation only: the verb decorators hold the handler's return type to it at compile time instead of validating every response.

authorize decides who may see the document, the page and the page's assets. It takes the same Authorize as @dunx/dashboard. A refused request gets a 404. If authorize returns a Response, for example a redirect to sign in, that response is sent as is.

Notes

• Add .meta({ id }) to a zod schema to put it in components/schemas. Without an id it is inlined wherever it is used. .strict() after .meta() drops the metadata, so call .meta() last.
• Prose belongs in description. An explorer labels a schema by title, which @dunx/openapi fills with the component name.
• The page embeds the document rather than fetching it, and loads the renderer's files same-origin from your own install. Nothing reaches a CDN, unless you turn Scalar's withDefaultFonts back on.
• renderer sits beside root rather than in forRootAsync's factory: the controller declares its routes before there is a container to run one.

License

MIT