Hogyan generálhatsz API dokumentációt Swagger-rel?

Question

Accepted Answer

A NestJS integrálódik a **Swagger/OpenAPI**-val a `@nestjs/swagger` segítségével, hogy **automatikusan interaktív API dokumentációt generáljon** a kódodból — kontrollerek, route-ok, DTO-k és dekorátorok alapján. Egy böngészhető felhasználói felületet hoz létre, ahol a fejlesztők felderíthetik és tesztelhetik az endpoint-okat, amely szinkronban marad a kóddal.

## Swagger beállítása

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

Néhány sor kóddal a Swagger megvizsgálja az alkalmazásodat és interaktív dokumentációt szolgáltat ki a `/api/docs` útvonalon — automatikusan tükrözve az route-jaid, paramétereid és DTO-id.

## DTO-k és válaszok dokumentálása

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

A `@ApiProperty` dekorátorok leírásokat, példákat és korlátozásokat adnak a DTO mezőkhöz, gazdagítva az generált sémát. (Sok automatikusan levezethető a TypeScript típusokból és a `class-validator` dekorátorokból — a `CLI plugin` még ezt a boilerplate-et is csökkentheti.)

## Endpoint-ok dokumentálása

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

A `@ApiTags`, `@ApiOperation` és `@ApiResponse` dekorátorokhoz hasonlóak leírásokat adnak, csoportosítják az endpoint-okat, és dokumentálják a lehetséges válaszokat.

## Mit kapsz

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

## Miért fontos

Az API dokumentáció elengedhetetlen minden olyan API-hoz, amelyet mások használnak — frontend csapatok, mobil alkalmazások, harmadik féltől származó integrálók vagy még az önmagad a jövőben — és a NestJS Swagger integrációja rendkívül egyszerűvé és megbízhatóvá teszi a magas minőségű dokumentáció készítését.

A legfontosabb előny, hogy a dokumentáció **automatikusan generálódik a kódból** (kontrollerek, route-ok, DTO-k és dekorátorok), így **szinkronban marad** a tényleges implementációval, ahelyett, hogy az kézzel írott dokumentációhoz hasonlóan elavulna.

Ez értékes tudás, mivel a jó API dokumentáció drasztikusan javítja a fejlesztői élményt és csökkenti az integráció fázisait: az interaktív **Swagger UI** lehetővé teszi a felhasználók számára, hogy közvetlenül a böngészőben fedezzék fel és *teszteljék* az endpoint-okat, a generált **OpenAPI specifikáció** pedig kliens SDK generálást és szerződés tesztelést lehet meghajtani.

Azt tudni, hogyan kell beállítani a Swagger-t, gazdagítani a dokumentációt dekorátorokkal (`@ApiProperty`, `@ApiTags`, `@ApiOperation`, `@ApiResponse`) és dokumentálni az autentikációt, gyakorlati, gyakran szükséges tudás — a jól dokumentált API-k professzionális standard és a minőségi backend munka jellemzője.

Mivel a NestJS a dekorátor/DTO struktúrát kihasználva automatikusan sok mindent generál (minimális extra erőfeszítéssel), szinte nincs ürügy arra, hogy ne legyen kiváló dokumentáció, így ez egy fontos, nagy értékű képesség a valós NestJS projektekben.