swagger
/swagger
Reference for Kavo's optional Swagger/OpenAPI integration — installing @nestjs/swagger, what generated routes document automatically, and what's still a manual addition. Use when adding API docs to a Kavo app, or answering "how do I get OpenAPI docs for these routes" questions.
- Author
- kavo-labs ↗
- Repository
- kavo ↗
- Licence
- MIT
- Last repository change
- 17.10.2026
Assessment and security
- Files in this package
- 1
- Scripts
- 0
- HTML comments
- 0
- URLs in SKILL.md
- 0
No signals detected. Repository changed on 17.10.2026, without references to retired models or APIs.
MIT, open: use and modify while retaining author attribution.
What it does and when to use it
Reference for Kavo's optional Swagger/OpenAPI integration — installing @nestjs/swagger, what generated routes document automatically, and what's still a manual addition. Use when adding API docs to a Kavo app, or answering "how do I get OpenAPI docs for these routes" questions.
Triggers from the description
Original author description
Reference for Kavo's optional Swagger/OpenAPI integration — installing @nestjs/swagger, what generated routes document automatically, and what's still a manual addition. Use when adding API docs to a Kavo app, or answering "how do I get OpenAPI docs for these routes" questions.
How it works
- Install
- Wiring the docs endpoint (main.ts)
- What's documented automatically, per generated route
- What is not generated (manual work today)
SKILL.md preview
---
name: swagger
description: Reference for Kavo's optional Swagger/OpenAPI integration — installing @nestjs/swagger, what generated routes document automatically, and what's still a manual addition. Use when adding API docs to a Kavo app, or answering "how do I get OpenAPI docs for these routes" questions.
---
# Swagger / OpenAPI reference
`@nestjs/swagger` is an **optional peer** of `@kavo/nest` — install it and
every generated route documents itself automatically; leave it out and
`@Kavo` costs nothing extra. No config flag turns this on or off: Kavo
detects the package at runtime (`createRequire(...).require("@nestjs/swagger")`,
cached, never throws if absent) and documents routes only when it's there.
Full detail: `docs/internals/architecture/10-nestjs-integration.md` §4.
## Install
```bash
npm install @nestjs/swagger
```
That's the only step — no `@Kavo` config option, no `KavoModule` option.
Existing `@Kavo`-decorated controllers pick up documentation the next time
the app boots with `@nestjs/swagger` present.
## Wiring the docs endpoint (`main.ts`)
This is plain Nest/Swagger, not Kavo-specific — `SwaggerModule` still needs
to be told to build and serve a document:
```ts
import { NestFactory } from "@nestjs/core";
import { DocumentBuilder, SwaggerModule } from "@nestjs/swagger";
import { AppModule } from "./app.module.js";
async function bootstrap(): Promise<void> {
const app = await NestFactory.create(AppModule);
const document = SwaggerModule.createDocument(
app,
new DocumentBuilder().setTitle("My API").setVersion("1.0.0").build(),
);
SwaggerModule.setup("docs", app, document); // → GET /docs
await app.listen(3000);
}
void bootstrap();
```
## What's documented automatically, per generated route
| Piece | Source |
| --------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Operation id | `<Entity>_<operationId>` (e.g. `User_findMany`) |
| `:id` path param | Every operation with an id in its route |
| Query params on list routes | `filter`/`sort`/`fields`/pagination/`include` shape (doc 05) |
| Request body schema | `schema.input.<slot>` when registered and it implements `toJSONSchema()` (ADR-0055); else the class-shaped schema for that slot, or the entity's ORM metadata (`ApiBody`) — see `dto-slots` |
| Error response schemas | Problem-details shape for 400/404, from the error catalog — see `error-handling` |
This applies identically whether the route came from plain generation,
`@Override`, or config-level `operations.<id>.meta` overrides — Swagger
metadata is applied through the same `applyRouteDecorators` step as the
route's method/param/status decorators.
## What is _not_ generated (manual work today)
- **A `schema` with no `toJSONSchema()`.** `KavoSchema.safeParse` alone gives
`registerKavoSchemas` nothing to introspect for docs — a schema documents
itself only if it also implements the optional `toJSONSchema(): object`
method (e.g. a thin wrapper calling Zod 4's `z.toJSONSchema(schema)`).
Without it, the schema still validates and narrows at runtime; the route
is documented from a class-shaped schema or the entity's ORM metadata instead, same as if no
`schema` were configured.
- **Allowlist-derived per-field query documentation.** `filter[field][op]=`
is documented as a generic shape, not expanded into one `ApiQuery` per
actual filterable/sortable field — that needs ORM metadata, which doesn't
exist yet at `@Kavo` decoration time (ADR-0012). If you want per-field
query docs today, add them yourself with plain `@ApiQuery()` on the
controller class.
- **Fully custom, registry-independent routes** (see `kavo-decorator`'s
section on those) get no automatic Swagger metadata — they're ordinary
Nest methods, so document them with plain `@ApiOperation()`/`@ApiBody()`
etc. exactly as you would on any non-`@Kavo` controller.
- **GraphQL routes** (see `graphql-binding`) are a separate binding entirely
and are not covered by this REST-focused Swagger integration.
Versions
The database has no other skills named swagger.
Database snapshot: 13.11.2026 · package version 3a0229bfc2f3 (SHA-256 digest of the entire package)
Downloads in the last 30 days: 0 · ranking
Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.
Similar skills
- 100nestjs-documentation
Automate Swagger/OpenAPI documentation and standardize API response schemas in NestJS. Use when generating OpenAPI specs, documenting paginated or generic responses, configuring the Nest CLI Swagger plugin, or publishing versioned API docs. - 95api-documentation-generator
Generate OpenAPI/Swagger specifications and API documentation from code or design. Use when creating API docs, generating OpenAPI specs, or documenting REST APIs. - 95openapi-specification-v2
OpenAPI (Swagger) 2.0 specification for describing REST APIs. Use when writing, validating, or interpreting Swagger 2.0 specs, generating clients/docs, or working with path/operation/parameter/response/schema/security definitions. - 100openapi-expert
Expert-level OpenAPI/Swagger specification for API design, documentation, and code generation. Use when the user mentions swagger, API specs, REST, API design, or documentation, or when the task involves OpenAPI Specification, Webhooks, or Polymorphism. - 100nextjs-integration
How to wire @kavo/next into an app's Next.js App Router — createKavoHandler, entity wiring, custom operations, and OpenAPI export. Use when a user is integrating Kavo into their own Next.js app, not when changing @kavo/next's own source (see… - 100openapi
OpenAPI/Swagger specification. Covers schema definition, paths, and documentation. Use for API documentation. USE WHEN: user mentions "OpenAPI", "Swagger", "API spec", "API documentation", "schema definition", "OpenAPI 3.0", "Swagger UI", asks about "how to write OpenAPI spec",…