Hvordan genererer du API-dokumentation med Swagger?

Question

Accepted Answer

NestJS integreres med **Swagger/OpenAPI** via `@nestjs/swagger` til at **auto-generere interaktiv API-dokumentation** fra din kode — controllere, ruter, DTOer og decorators. Den producerer en browser-venlig brugerflade, hvor udviklere kan udforske og teste endpoints, og holdes synkroniseret med koden.

## Opsætning af Swagger

```ts
// main.ts
import { SwaggerModule, DocumentBuilder } from "@nestjs/swagger";

const config = new DocumentBuilder()
  .setTitle("Users API")
  .setDescription("The users API documentation")
  .setVersion("1.0")
  .addBearerAuth()                       // document JWT auth
  .build();

const document = SwaggerModule.createDocument(app, config);
SwaggerModule.setup("api/docs", app, document);   // serve the UI at /api/docs
```

Med blot nogle få linjer scanner Swagger din app og serverer interaktiv dokumentation på `/api/docs` — og afspejler automatisk dine ruter, parametre og DTOer.

## Dokumentation af DTOer og responses

```ts
export class CreateUserDto {
  @ApiProperty({ example: "ann@example.com", description: "User email" })
  email: string;

@ApiProperty({ minLength: 8 })
  password: string;

@ApiPropertyOptional()                 // optional field in the docs
  age?: number;
}
```

`@ApiProperty` decorators tilføjer beskrivelser, eksempler og begrænsninger til DTO-felter, hvilket bedrere det genererede skema. (Meget infereres automatisk fra TypeScript-typer og `class-validator` decorators — `CLI plugin`'en kan reducere selv denne boilerplate.)

## Dokumentation af endpoints

```ts
@ApiTags("users")                        // group endpoints in the UI
@Controller("users")
export class UsersController {
  @Post()
  @ApiOperation({ summary: "Create a user" })
  @ApiResponse({ status: 201, description: "User created", type: User })
  @ApiResponse({ status: 400, description: "Invalid input" })
  create(@Body() dto: CreateUserDto) {}
}
```

Decorators som `@ApiTags`, `@ApiOperation` og `@ApiResponse` tilføjer beskrivelser, grupperer endpoints og dokumenterer mulige responses.

## Hvad du får

```text
✓ Interactive UI (Swagger UI) — browse, read, and TEST endpoints in the browser
✓ Auto-generated, always in sync with the code (no separate doc to maintain)
✓ The OpenAPI spec (JSON) — usable to generate client SDKs, for contract testing, etc.
✓ Request/response schemas, validation rules, auth requirements all documented
```

## Hvorfor det betyder noget

API-dokumentation er afgørende for ethvert API, der forbruges af andre — frontend-teams, mobile apps, tredjeparts-integratorer eller endda din fremtidige selv — og NestJS's Swagger-integration gør det bemærkelsesværdigt nemt og pålideligt at producere dokumentation af høj kvalitet.

Hovedfordelen er, at dokumentation **auto-genereres fra koden** (controllere, ruter, DTOer og decorators), så den forbliver **synkroniseret** med den faktiske implementering, i stedet for at blive forældet som håndskreven dokumentation uundgåeligt gør.

Det er værdifuldt at forstå, fordi god API-dokumentation dramatisk forbedrer udvikler-oplevelsen og reducerer integrationsfriktion: den interaktive **Swagger UI** lader forbrugere udforske og *teste* endpoints direkte i browseren, og den genererede **OpenAPI-spec** kan drive klient-SDK-generering og kontrakttesting.

At vide, hvordan man sætter Swagger op, beriber dokumentationen med decorators (`@ApiProperty`, `@ApiTags`, `@ApiOperation`, `@ApiResponse`) og dokumenterer autentificering, er praktisk, hyppigt-benyttet viden — velskrevet API-dokumentation er en professionel standard og et kendetegn på kvalitet back-end-arbejde.

Fordi NestJS anvender sin decorator-/DTO-struktur til at generere så meget automatisk (med minimal ekstra indsats), er der lille undskyldning for ikke at have fremragende dokumentation, hvilket gør dette til en vigtig, høj-værdi-kapabilitet i rigtige NestJS-projekter.