Hvordan genererer du API-dokumentasjon med Swagger?

Question

Accepted Answer

NestJS integreres med **Swagger/OpenAPI** via `@nestjs/swagger` for å **auto-generere interaktiv API-dokumentasjon** fra koden din — controllere, ruter, DTOer og dekoratorer. Det produserer et brukervennlig grensesnitt hvor utviklere kan utforske og teste endepunkter, og det holdes synkronisert med koden.

## Oppsett av 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 noen få linjer skanner Swagger appen din og serverer interaktiv dokumentasjon på `/api/docs` — som automatisk reflekterer rutene dine, parametre og DTOer.

## Dokumentering av DTOer og respons

```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` dekoratorer legger til beskrivelser, eksempler og begrensninger på DTO-felt, og berikter det genererte skjemaet. (Mye utledes automatisk fra TypeScript-typer og `class-validator` dekoratorer — `CLI-pluginen` kan redusere enda mer boilerplate.)

## Dokumentering av endepunkter

```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) {}
}
```

Dekoratorer som `@ApiTags`, `@ApiOperation` og `@ApiResponse` legger til beskrivelser, grupperer endepunkter og dokumenterer mulige respons.

## Hva 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 betyr noe

API-dokumentasjon er essensiell for ethvert API som brukes av andre — frontend-team, mobilapper, integratører fra tredjeparter, eller til og med deg selv i framtiden — og NestJS sin Swagger-integrasjon gjør produksjon av høykvalitets dokumentasjon bemerkelsesverdig enkel og pålitelig.

Hovedfordelen er at dokumentasjonen er **auto-generert fra koden** (controllere, ruter, DTOer og dekoratorer), så den forblir **synkronisert** med den faktiske implementeringen i stedet for å bli utdatert slik håndskrevet dokumentasjon uunngåelig gjør.

Å forstå det er verdifullt fordi god API-dokumentasjon dramatisk forbedrer utvikleres erfaring og reduserer integrasjonsfriksjon: det interaktive **Swagger UI** lar forbrukere utforske og *teste* endepunkter direkte i nettleseren, og den genererte **OpenAPI-spesifikasjonen** kan drive generering av klient-SDK-er og kontraktesting.

Å vite hvordan man setter opp Swagger, berikter dokumentasjonen med dekoratorer (`@ApiProperty`, `@ApiTags`, `@ApiOperation`, `@ApiResponse`), og dokumenterer autentisering er praktisk, hyppig nødvendig kunnskap — godt dokumenterte APIer er en profesjonell standard og et tegn på kvalitet i back-end-arbeid.

Fordi NestJS utnytter sin dekorator-/DTO-struktur til å generere så mye automatisk (med minimal ekstra innsats), er det liten unnskyldning for ikke å ha utmerket dokumentasjon, noe som gjør dette til en viktig, høy-verdi evne i virkelige NestJS-prosjekter.