Kuinka generoida API-dokumentaatiota Swaggerilla?

Question

Accepted Answer

NestJS integroi **Swagger/OpenAPI**:n `@nestjs/swagger`-kirjaston kautta **automaattisesti generoituihin interaktiivisiin API-dokumentaatioihin** koodistasi — kontrollerit, reitit, DTOt ja dekoraattorit. Se tuottaa selailun mahdollistavan käyttöliittymän, jossa kehittäjät voivat tutkia ja testata päätepisteitä, ja se pysyy synkronoituna koodin kanssa.

## Swaggerin konfigurointi

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

Muutamalla rivillä Swagger skannaa sovelluksesi ja tarjoilee interaktiivista dokumentaatiota osoitteesta `/api/docs` — heijastaa automaattisesti reitit, parametrit ja DTOt.

## DTOjen ja vastausten dokumentointi

```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`-dekoraattorit lisäävät kuvauksia, esimerkkejä ja rajoitteita DTO-kenttiin, rikastuttaen luodun skeeman. (Suuri osa päätellään automaattisesti TypeScript-tyypeistä ja `class-validator`-dekoraattoreista — `CLI-liitännäinen` voi vähentää jopa tätä boilerplate-koodia.)

## Päätepisteiden dokumentointi

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

Dekoraattorit kuten `@ApiTags`, `@ApiOperation` ja `@ApiResponse` lisäävät kuvauksia, ryhmittelevät päätepisteitä ja dokumentoivat mahdollisia vastauksia.

## Mitä saat

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

## Miksi se on tärkeää

API-dokumentaatio on välttämätöntä jokaiselle API:lle, jota käyttävät muut — frontend-tiimit, mobiilisovellukset, kolmannen osapuolen integraattorit tai jopa sinä tulevaisuudessa — ja NestJS:n Swagger-integraatio tekee korkealaatuisen dokumentaation tuottamisesta huomattavan helppoa ja luotettavaa.

Pääetu on, että dokumentaatio **generoidaan automaattisesti koodista** (kontrollerit, reitit, DTOt ja dekoraattorit), joten se pysyy **synkronoituna** todellisen implementaation kanssa sen sijaan, että se hajoaisi irti kuten käsinkirjoitetut dokumentaatiot väistämättä tekevät.

Sen ymmärtäminen on arvokasta, koska hyvä API-dokumentaatio parantaa kehittäjän kokemusta dramaattisesti ja vähentää integraation kitkaa: interaktiivinen **Swagger-käyttöliittymä** antaa käyttäjille mahdollisuuden tutkia ja *testata* päätepisteitä suoraan selaimessa, ja generoitu **OpenAPI-spesifikaatio** voi ajaa asiakas-SDK:n generointia ja sopimustestaamista.

Tieto siitä, kuinka konfiguroida Swagger, rikastuttaa dokumentaatiota dekoraattoreilla (`@ApiProperty`, `@ApiTags`, `@ApiOperation`, `@ApiResponse`) ja dokumentoidaan autentikointi, on käytännöllinen, usein tarvittava tieto — hyvin dokumentoidut API:t ovat ammattimainen standardi ja laadun tunnusmerkki back-end-työssä.

Koska NestJS hyödyntää sen dekoraattori-/DTO-rakennetta generoimaan niin paljon automaattisesti (minimaalisella lisätyöllä), ei ole mitään tekosyytä olla loistavaa dokumentaatiota, joten tämä on tärkeä, korkea-arvoinen ominaisuus oikean NestJS-projektissa.