Comment générer une documentation API avec Swagger ?

Question

Accepted Answer

NestJS s'intègre avec **Swagger/OpenAPI** via `@nestjs/swagger` pour **générer automatiquement une documentation API interactive** à partir de votre code — contrôleurs, routes, DTOs et décorateurs. Elle produit une interface consultable où les développeurs peuvent explorer et tester les endpoints, maintenue en synchronisation avec le code.

## Configuration de 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
```

Avec quelques lignes, Swagger analyse votre application et sert une documentation interactive à `/api/docs` — reflétant automatiquement vos routes, paramètres et DTOs.

## Documenter les DTOs et réponses

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

Les décorateurs `@ApiProperty` ajoutent des descriptions, des exemples et des contraintes aux champs DTO, enrichissant le schéma généré. (Une grande partie est déduite automatiquement à partir des types TypeScript et des décorateurs `class-validator` — le `CLI plugin` peut réduire encore davantage ce code générique.)

## Documenter les endpoints

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

Les décorateurs comme `@ApiTags`, `@ApiOperation` et `@ApiResponse` ajoutent des descriptions, regroupent les endpoints et documentent les réponses possibles.

## Ce que vous obtenez

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

## Pourquoi c'est important

La documentation API est essentielle pour toute API consommée par d'autres — équipes frontend, applications mobiles, intégrateurs tiers, ou même votre futur moi — et l'intégration Swagger de NestJS rend la production de documentation de haute qualité remarquablement facile et fiable.

L'avantage clé est que la documentation est **auto-générée à partir du code** (contrôleurs, routes, DTOs et décorateurs), elle reste donc **en synchronisation** avec l'implémentation réelle plutôt que de devenir obsolète comme le font inévitablement les docs écrites à la main.

Comprendre cela est précieux car une bonne documentation API améliore dramatiquement l'expérience du développeur et réduit les frictions d'intégration : l'**interface utilisateur Swagger** interactive permet aux consommateurs d'explorer et de *tester* les endpoints directement dans le navigateur, et la **spécification OpenAPI** générée peut piloter la génération de SDK client et le test de contrats.

Savoir configurer Swagger, enrichir la documentation avec des décorateurs (`@ApiProperty`, `@ApiTags`, `@ApiOperation`, `@ApiResponse`) et documenter l'authentification est une connaissance pratique et fréquemment nécessaire — les API bien documentées sont une norme professionnelle et une marque de qualité du travail back-end.

Comme NestJS exploite sa structure décorateur/DTO pour générer automatiquement beaucoup de choses (avec un effort supplémentaire minimal), il n'y a guère d'excuses pour ne pas avoir une documentation excellente, ce qui rend cette capacité importante et très utile dans les vrais projets NestJS.