OpenAPI / Swagger

Nova can auto-generate OpenAPI 3.0 documentation from your route definitions, Zod schemas, and decorators.

Setup

main.ts TypeScript

const app = await NovaFactory.create({
  openapi: {
    title: 'My API',
    version: '1.0.0',
    description: 'A sample API',
  },
});

// Register OpenAPI
await app.openAPI();

// Enable Swagger UI at /docs
await app.enableDocs();

💡 Tip

Only enable Swagger in development to avoid exposing your API schema in production:

Conditional Docs TypeScript

if (app.env.isDevelopment()) {
  await app.openAPI();
  await app.enableDocs();
}

Including Routes in the Schema

By default, routes are not included in the OpenAPI schema. Set includeInSchema: true in the route options:

Example TypeScript

@Get('', {
  includeInSchema: true,
  summary: 'List all users',
  description: 'Returns a list of all registered users',
  tags: ['Users'],
  responseModel: z.array(UserSchema),
})
async findAll() { ... }

What Gets Generated

Nova automatically extracts the following information for the OpenAPI schema:

Body schema — From @Body Zod schemas (converted to JSON Schema)
Response schema — From responseModel Zod schema
Path parameters — From @Path decorators with their types
Query parameters — From @Query decorators (required/optional)
Security — If @RequiresAuth() is present, BearerAuth/CookieAuth is added

Previous ← Exceptions Next StatusHTTP →