Come generi la documentazione API con Swagger?

Question

Accepted Answer

NestJS si integra con **Swagger/OpenAPI** tramite `@nestjs/swagger` per **generare automaticamente documentazione API interattiva** dal tuo codice — controller, route, DTO e decorator. Produce un'interfaccia esplorabile dove gli sviluppatori possono scoprire e testare gli endpoint, mantenuta sincronizzata con il codice.

## Configurazione di 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
```

Con poche righe, Swagger scansiona la tua app e distribuisce la documentazione interattiva in `/api/docs` — riflettendo automaticamente le tue route, parametri e DTO.

## Documentazione di DTO e risposte

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

I decorator `@ApiProperty` aggiungono descrizioni, esempi e vincoli ai campi del DTO, arricchendo lo schema generato. (Molto viene dedotto automaticamente dai tipi TypeScript e dai decorator `class-validator` — il `CLI plugin` può ridurre ulteriormente questo boilerplate.)

## Documentazione degli endpoint

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

I decorator come `@ApiTags`, `@ApiOperation` e `@ApiResponse` aggiungono descrizioni, raggruppano gli endpoint e documentano le possibili risposte.

## Cosa ottieni

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

## Perché è importante

La documentazione API è essenziale per qualsiasi API consumata da altri — team frontend, app mobile, integratori terze parti, o anche il tuo futuro io — e l'integrazione Swagger di NestJS rende la produzione di documentazione di alta qualità straordinariamente facile e affidabile.

Il vantaggio principale è che la documentazione è **generata automaticamente dal codice** (controller, route, DTO e decorator), quindi rimane **sincronizzata** con l'implementazione effettiva piuttosto che diventare obsoleta come inevitabilmente accade con la documentazione scritta a mano.

Comprendere questo è prezioso perché una buona documentazione API migliora drasticamente l'esperienza dello sviluppatore e riduce l'attrito dell'integrazione: la **Swagger UI** interattiva consente ai consumer di esplorare e *testare* gli endpoint direttamente nel browser, e la **specifica OpenAPI** generata può guidare la generazione di client SDK e il contract testing.

Sapere come configurare Swagger, arricchire la documentazione con decorator (`@ApiProperty`, `@ApiTags`, `@ApiOperation`, `@ApiResponse`) e documentare l'autenticazione è una conoscenza pratica e frequentemente necessaria — le API ben documentate sono uno standard professionale e un segno distintivo del lavoro di back-end di qualità.

Poiché NestJS sfrutta la sua struttura di decorator/DTO per generare così tante cose automaticamente (con uno sforzo minimo aggiuntivo), non c'è praticamente scusa per non avere documentazione eccellente, rendendo questa una capacità importante e di alto valore nei progetti NestJS reali.