Swagger

Documenter un contrôleur / endpoint

Les descriptions des endpoints se mettent directement dans les contrôleurs avec les décorateurs fournis par @nestjs/swagger.

Décorateurs utiles :

• @ApiTags('nom') — regroupe les endpoints dans la UI.
• @ApiOperation({ summary, description }) — résumé et description de l'endpoint.
• @ApiResponse({ status, description, type }) — description d'une réponse HTTP; type peut pointer sur un DTO.
• @ApiQuery({ name, required, description, type }) — paramètres query.
• @ApiParam({ name, description, type }) — paramètres de route (path).
• @ApiBearerAuth() / @ApiSecurity() — sécuriser la doc si vous utilisez JWT/OAuth.
• @ApiExcludeEndpoint() — pour exclure un endpoint de la doc.

@Controller('api/stores')
@ApiTags('stores')
export class StoresController {
  @Get()
  @ApiOperation({ summary: 'Liste des magasins', description: 'Récupération paginée de tous les magasins' })
  @ApiResponse({ status: 200, description: 'Liste des magasins retournée' })
  @ApiQuery({ name: 'page', required: false, description: 'Numéro de page (défaut: 1)', type: Number })
  @ApiQuery({ name: 'limit', required: false, description: "Limite par page (défaut: 10)", type: Number })
  async getAllStores(@Query() paginationDto: PaginationDto) {
    // ...implementation
  }

  @Get(':id')
  @ApiOperation({ summary: "Récupérer un magasin", description: "Récupération d'un magasin par son ID" })
  @ApiResponse({ status: 200, description: 'Magasin trouvé' })
  @ApiResponse({ status: 404, description: 'Magasin non trouvé' })
  @ApiParam({ name: 'id', description: 'Identifiant numérique du magasin', type: Number })
  async getStoreById(@Param('id') id: number) {
    // ...implementation
  }
}

Documenter les DTOs (schémas)

Les DTOs (classes TypeScript) servent de schémas. Utilisez @ApiProperty() pour décrire chaque propriété.

export class StoreDto {
  @ApiProperty({ description: 'Identifiant unique', example: 1 })
  id: number;

  @ApiProperty({ description: 'Nom du magasin', example: 'Store Central Paris' })
  name: string;

  @ApiProperty({ description: "Adresse complète", example: '123 Rue de Rivoli' })
  address: string;

  @ApiProperty({ description: 'Ville', example: 'Paris' })
  city: string;
}

Documenter les corps de requête (request body)

Pour les endpoints qui reçoivent un body, utilisez @ApiResponse({ type: YourDto }) et, si besoin, @ApiBody({ type: CreateDto }) :

@Post()
@ApiBody({ type: CreateStoreDto })
@ApiResponse({ status: 201, description: 'Store créé', type: StoreDto })
async create(@Body() dto: CreateStoreDto) { }

Auth & sécurisation de la doc

Si vous protégez des routes avec JWT/Bearer :

• Ajoutez @ApiBearerAuth() sur les controllers/endpoints protégés.
• Dans main.ts, vous pouvez ajouter la sécurité globale au DocumentBuilder :

const config = new DocumentBuilder()
  .addBearerAuth({ type: 'http', scheme: 'bearer', bearerFormat: 'JWT' })
  .build();

Cela ajoutera l'UI pour renseigner un token dans Swagger.