Hur genererar du API-dokumentation med Swagger?

Question

Accepted Answer

NestJS integreras med **Swagger/OpenAPI** via `@nestjs/swagger` för att **automatiskt generera interaktiv API-dokumentation** från din kod — controllers, routes, DTOs och decorators. Det producerar ett användarvänligt UI där utvecklare kan utforska och testa endpoints, vilket hålls synkroniserat med koden.

## Ställa in 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 några rader skannar Swagger din app och servar interaktiv dokumentation på `/api/docs` — som automatiskt återspeglar dina routes, parametrar och DTOs.

## Dokumentera DTOs och 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 lägger till beskrivningar, exempel och begränsningar för DTO-fält, vilket berikar det genererade schemat. (Mycket kan automatiskt härledas från TypeScript-typer och `class-validator` decorators — `CLI-pluginen` kan minska även denna boilerplate.)

## Dokumentera 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` och `@ApiResponse` lägger till beskrivningar, grupperar endpoints och dokumenterar möjliga responses.

## Vad 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
```

## Varför det spelar roll

API-dokumentation är väsentlig för alla API:er som konsumeras av andra — frontend-team, mobilappar, tredjepartsintegratörer eller till och med din framtida själv — och NestJS:s Swagger-integrering gör det anmärkningsvärt enkelt och tillförlitligt att producera högkvalitativ dokumentation.

Huvudfördelens är att dokumentationen är **automatiskt genererad från koden** (controllers, routes, DTOs och decorators), så den förblir **synkroniserad** med den faktiska implementeringen snarare än att driva bort från datumet som handskrivna docs oundvikligen gör.

Att förstå det är värdefullt eftersom bra API-dokumentation dramatiskt förbättrar utvecklarupplevelsen och minskar integreringsfriktion: det interaktiva **Swagger UI** låter konsumenter utforska och *testa* endpoints direkt i webbläsaren, och den genererade **OpenAPI-specifikationen** kan driva klient-SDK-generering och kontraktstestning.

Att veta hur man ställer in Swagger, berikar dokumentationen med decorators (`@ApiProperty`, `@ApiTags`, `@ApiOperation`, `@ApiResponse`) och dokumenterar autentisering är praktisk, ofta behövd kunskap — väldokumenterade API:er är en professionell standard och en kännetecken på högkvalitativ back-end-arbete.

Eftersom NestJS utnyttjar sin decorator/DTO-struktur för att automatiskt generera så mycket (med minimal extra ansträngning), finns det liten anledning att inte ha utmärkta docs, vilket gör detta till en viktig, högvärd förmåga i verkliga NestJS-projekt.