Cum generezi documentația API cu Swagger?

Question

Accepted Answer

NestJS se integrează cu **Swagger/OpenAPI** prin `@nestjs/swagger` pentru a **genera automat documentația API interactivă** din codul tău — controllere, rute, DTO-uri și decoratori. Produce o interfață accesibilă în care desarrollatorii pot explora și testa endpoint-uri, păstrată în sincronizare cu codul.

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

Cu câteva linii, Swagger scanează aplicația și servește documente interactive la `/api/docs` — reflectând automat rutele, parametrii și DTO-urile.

## Documentarea DTO-urilor și răspunsurilor

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

Decoratoarele `@ApiProperty` adaugă descrieri, exemple și constrângeri câmpurilor DTO, îmbogățind schema generată. (Mult este dedus automat din tipurile TypeScript și decoratorii `class-validator` — pluginul CLI poate reduce chiar și această plăcintă)

## Documentarea endpoint-urilor

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

Decoratoarele precum `@ApiTags`, `@ApiOperation` și `@ApiResponse` adaugă descrieri, grupează endpoint-uri și documentează răspunsurile posibile.

## Ce primești

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

## De ce conteaza

Documentația API este esențială pentru orice API consumată de alții — echipe frontend, aplicații mobile, integratori terți, sau chiar tu în viitor — și integrarea Swagger a NestJS-ului face producerea de documente de înaltă calitate remarcabil de ușoară și fiabilă.

Avantajul cheie este că documentația este **auto-generată din cod** (controllere, rute, DTO-uri și decoratori), deci rămâne **sincronizată** cu implementarea reală în loc să se depărteze din data ca documentele scrise manual inevitabil fac.

Înțelegerea acesteia este valoroasă deoarece documentele API bune îmbunătățesc dramatic experiența dezvoltatorului și reduc fricțiunea integrării: **interfața Swagger** interactivă permite consumatorilor să exploreze și să *testeze* endpoint-uri direct în browser, iar **specificația OpenAPI** generată poate conduce generarea SDK client și testarea contractelor.

Știind cum să configurezi Swagger, să îmbogățești documentele cu decoratori (`@ApiProperty`, `@ApiTags`, `@ApiOperation`, `@ApiResponse`), și cum să documentezi autentificarea este cunoștință practică, frecvent necesară — API-urile bine documentate sunt un standard profesional și o caracteristică a muncii backend de calitate.

Deoarece NestJS profită de structura sa decorator/DTO pentru a genera atât de mult automat (cu efort minim suplimentar), nu este scuză pentru a nu avea documente excelente, făcând aceasta o capabilitate importantă și cu valoare înaltă în proiectele NestJS din lumea reală.