Skip to content
Skills Library
Programming · Learning & explanation

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.

Repository
kavo ↗
Licence
MIT
Last repository change
17.10.2026

Assessment and security

100/ 100Class: good
Format25 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content35 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
1
Scripts
0
HTML comments
0
URLs in SKILL.md
0
Deprecation

No signals detected. Repository changed on 17.10.2026, without references to retired models or APIs.

Licence

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

how do I get OpenAPI docs for these routes
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

  1. Install
  2. Wiring the docs endpoint (main.ts)
  3. What's documented automatically, per generated route
  4. What is not generated (manual work today)
Original SKILL.md headings · 82 lines, 483 words
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",…

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.