Avez-vous une question? (216) 97 656 803 hajjriadh@gmail.com
NestJS

Documenter les DTO, les routes et l'authentification (@ApiProperty, @ApiBearerAuth)

Cette leçon produit une documentation complète et exacte d'une API protégée par JWT. Les DTO sont décrits avec @ApiProperty (exemples, énumérations, formats), les routes avec @ApiTags, @ApiOperation, ...

0 chapitres 0 QCM Accès gratuit
Documenter les DTO, les routes et l'authentification (@ApiProperty, @ApiBearerAuth)

À propos de ce cours

Cette leçon produit une documentation complète et exacte d'une API protégée par JWT. Les DTO sont décrits avec @ApiProperty (exemples, énumérations, formats), les routes avec @ApiTags, @ApiOperation, @ApiParam, @ApiQuery et les réponses de succès et d'erreur, y compris une réponse paginée générique. L'authentification est déclarée avec addBearerAuth et @ApiBearerAuth, puis testée dans Swagger UI avec le bouton Authorize. L'exécution révèle deux pièges : PartialType importé du mauvais paquet et exemples d'erreur trompeurs. Enfin, le document sert à générer les types TypeScript du client Angular. Captures réelles et activités corrigées.

Objectifs de la leçon

  • Décrire les DTO avec @ApiProperty et @ApiPropertyOptional.
  • Documenter les routes : résumé, paramètres, réponses et erreurs.
  • Documenter l'authentification JWT et l'utiliser dans Swagger UI.
  • Exploiter le document pour générer les types d'un client.

Décorateurs de @nestjs/swagger

Les décorateurs se placent sur la classe du contrôleur, sur les méthodes et sur les propriétés des DTO.

Le projet de la leçon

Nous documentons l'API des stagiaires, protégée par un guard JWT global avec @Public() (chapitre 13, ici simplifié : un seul compte, sans base de données, pour se concentrer sur la documentation). Les décorateurs sont écrits explicitement, sans le plugin, pour bien voir le rôle de chacun.

1. Les DTO : @ApiProperty

📄 src/stagiaires/stagiaire.dto.ts

import { ApiProperty, ApiPropertyOptional, PartialType } from '@nestjs/swagger';
import { IsEmail, IsIn, IsInt, IsOptional, IsString, Length, Max, Min } from 'class-validator';

export const GROUPES = ['DEV101', 'RES201', 'MM301'] as const;

export class CreerStagiaireDto {
  @ApiProperty({ description: 'Nom complet', example: 'Sami Ben Ali', minLength: 2, maxLength: 60 })
  @IsString()
  @Length(2, 60)
  nom: string;

  @ApiProperty({ description: 'Adresse e-mail (unique)', example: 'sami@exemple.tn', format: 'email' })
  @IsEmail()
  email: string;

  @ApiProperty({ enum: GROUPES, enumName: 'Groupe', example: 'DEV101' })
  @IsIn(GROUPES)
  groupe: string;

  @ApiPropertyOptional({ minimum: 16, maximum: 60, example: 21, type: 'integer' })
  @IsOptional()
  @IsInt()
  @Min(16)
  @Max(60)
  age?: number;
}

// PartialType de @nestjs/swagger : rend tout optionnel ET conserve la documentation
export class ModifierStagiaireDto extends PartialType(CreerStagiaireDto) {}

// Ce que l'API renvoie
export class StagiaireDto extends CreerStagiaireDto {
  @ApiProperty({ example: 1 })
  id: number;
}
  • @ApiProperty: propriété obligatoire ; @ApiPropertyOptional: facultative. Options courantes : description, example, enum, format, minimum/maximum, minLength, type ('integer', [String] pour un tableau, une classe pour un objet imbriqué).
  • enumName: 'Groupe' crée un schéma réutilisable Groupe au lieu de répéter la liste partout.
  • Les règles de validation restent assurées par class-validator : @ApiProperty ne fait que décrire. Les deux doivent rester cohérentes, d'où l'intérêt du plugin (leçon 14.2) qui les déduit l'une de l'autre.
  • PartialType, PickType, OmitType, IntersectionType s'importent de @nestjs/swagger (et non de @nestjs/mapped-types comme au chapitre 08) : ils conservent alors la documentation. Le résultat ci-dessous le démontre.
  • @ApiHideProperty() masque une propriété (un champ interne qui ne doit pas apparaître dans la documentation).
2. Les erreurs et la pagination

📄 src/commun/erreur.dto.ts

import { ApiProperty } from '@nestjs/swagger';

// Forme des erreurs renvoyées par NestJS (leçon 9.3), pour la documentation
export class ErreurDto {
  @ApiProperty({ example: 404 })
  statusCode: number;

  @ApiProperty({ oneOf: [{ type: 'string' }, { type: 'array', items: { type: 'string' } }], example: 'Stagiaire 9 introuvable' })
  message: string | string[];

  @ApiProperty({ example: 'Not Found' })
  error: string;
}

📄 src/commun/page.dto.ts

import { applyDecorators, Type } from '@nestjs/common';
import { ApiExtraModels, ApiOkResponse, ApiProperty, getSchemaPath } from '@nestjs/swagger';

export class PageDto<T> {
  data: T[];

  @ApiProperty({ example: 1 })
  page: number;

  @ApiProperty({ example: 10 })
  limite: number;

  @ApiProperty({ example: 42 })
  total: number;
}

// Décorateur composé : documente une réponse PageDto<Modele>
export const ApiPageResponse = <M extends Type<unknown>>(modele: M, description = 'Page de résultats') =>
  applyDecorators(
    ApiExtraModels(PageDto, modele),
    ApiOkResponse({
      description,
      schema: {
        allOf: [
          { $ref: getSchemaPath(PageDto) },
          { properties: { data: { type: 'array', items: { $ref: getSchemaPath(modele) } } } },
        ],
      },
    }),
  );

ErreurDto décrit la forme des erreurs de NestJS (leçon 9.3). PageDto<T> est générique : TypeScript efface le T à l'exécution, Swagger ne peut donc pas le deviner. Le décorateur composé ApiPageResponse (avec applyDecorators, leçon 9.6) déclare les modèles (ApiExtraModels) et construit le schéma : « un PageDto dont data est un tableau de StagiaireDto ».

3. Les routes

📄 src/stagiaires/stagiaires.controller.ts

import { Body, Controller, DefaultValuePipe, Delete, Get, HttpCode, NotFoundException, Param, ParseIntPipe, Patch, Post, Query } from '@nestjs/common';
import {
  ApiBadRequestResponse, ApiBearerAuth, ApiCreatedResponse, ApiForbiddenResponse, ApiNoContentResponse, ApiNotFoundResponse,
  ApiOkResponse, ApiOperation, ApiParam, ApiQuery, ApiTags, ApiUnauthorizedResponse,
} from '@nestjs/swagger';
import { ErreurDto } from '../commun/erreur.dto';
import { ApiPageResponse, PageDto } from '../commun/page.dto';
import { CreerStagiaireDto, GROUPES, ModifierStagiaireDto, StagiaireDto } from './stagiaire.dto';

@ApiTags('Stagiaires')
@ApiBearerAuth()                                                   // toutes les routes exigent le jeton
@ApiUnauthorizedResponse({ description: 'Jeton absent, invalide ou expiré', type: ErreurDto })
@Controller('stagiaires')
export class StagiairesController {
  private stagiaires: StagiaireDto[] = [
    { id: 1, nom: 'Sami Ben Ali', email: 'sami@exemple.tn', groupe: 'DEV101', age: 21 },
    { id: 2, nom: 'Ines Trabelsi', email: 'ines@exemple.tn', groupe: 'RES201', age: 23 },
  ];

  @Get()
  @ApiOperation({ summary: 'Lister les stagiaires', description: 'Liste paginée, filtrable par groupe.' })
  @ApiQuery({ name: 'groupe', required: false, enum: GROUPES, enumName: 'Groupe' })
  @ApiQuery({ name: 'page', required: false, type: Number, example: 1 })
  @ApiPageResponse(StagiaireDto)
  lister(
    @Query('groupe') groupe?: string,
    @Query('page', new DefaultValuePipe(1), ParseIntPipe) page = 1,
  ): PageDto<StagiaireDto> {
    const liste = this.stagiaires.filter((s) => !groupe || s.groupe === groupe);
    return { data: liste.slice((page - 1) * 10, page * 10), page, limite: 10, total: liste.length };
  }

  @Get(':id')
  @ApiOperation({ summary: 'Consulter un stagiaire' })
  @ApiParam({ name: 'id', description: 'Identifiant du stagiaire', example: 1 })
  @ApiOkResponse({ type: StagiaireDto })
  @ApiNotFoundResponse({ description: 'Stagiaire introuvable', type: ErreurDto })
  trouver(@Param('id', ParseIntPipe) id: number): StagiaireDto {
    const s = this.stagiaires.find((x) => x.id === id);
    if (!s) throw new NotFoundException(`Stagiaire ${id} introuvable`);
    return s;
  }

  @Post()
  @ApiOperation({ summary: 'Inscrire un stagiaire' })
  @ApiCreatedResponse({ description: 'Stagiaire créé', type: StagiaireDto })
  @ApiBadRequestResponse({ description: 'Données invalides', type: ErreurDto })
  creer(@Body() dto: CreerStagiaireDto): StagiaireDto {
    const s = { id: this.stagiaires.length + 1, ...dto };
    this.stagiaires.push(s);
    return s;
  }

  @Patch(':id')
  @ApiOperation({ summary: 'Modifier un stagiaire' })
  @ApiOkResponse({ type: StagiaireDto })
  @ApiNotFoundResponse({ type: ErreurDto })
  modifier(@Param('id', ParseIntPipe) id: number, @Body() dto: ModifierStagiaireDto): StagiaireDto {
    const s = this.trouver(id);
    Object.assign(s, dto);
    return s;
  }

  @Delete(':id')
  @HttpCode(204)
  @ApiOperation({ summary: 'Supprimer un stagiaire', description: 'Réservé aux administrateurs.' })
  @ApiNoContentResponse({ description: 'Supprimé' })
  @ApiForbiddenResponse({ description: 'Rôle insuffisant', type: ErreurDto })
  supprimer(@Param('id', ParseIntPipe) id: number) {
    this.stagiaires = this.stagiaires.filter((s) => s.id !== id);
  }
}
  • @ApiTags groupe les routes ; placé sur la classe, il s'applique à toutes.
  • @ApiOperation({ summary, description }): le titre court affiché à côté de la route, et un texte plus long.
  • @ApiParam et @ApiQuery précisent les paramètres (les paramètres de requête facultatifs doivent être déclarés required: false).
  • @ApiOkResponse, @ApiCreatedResponse, @ApiNoContentResponse, @ApiBadRequestResponse, @ApiNotFoundResponse… sont des raccourcis de @ApiResponse({ status, description, type }). type: StagiaireDto renvoie au schéma ; type: [StagiaireDto] pour un tableau.
  • Déclarer le type de retour des méthodes (: StagiaireDto) rend le code plus clair et permet au plugin de deviner la réponse.
4. L'authentification

📄 src/auth/auth.ts

import { Body, CanActivate, Controller, ExecutionContext, HttpCode, Injectable, Post, SetMetadata, UnauthorizedException } from '@nestjs/common';
import { Reflector } from '@nestjs/core';
import { JwtService } from '@nestjs/jwt';
import { ApiOkResponse, ApiOperation, ApiProperty, ApiTags, ApiUnauthorizedResponse } from '@nestjs/swagger';
import { IsEmail, IsString } from 'class-validator';
import { ErreurDto } from '../commun/erreur.dto';

export const Public = () => SetMetadata('public', true);

export class ConnexionDto {
  @ApiProperty({ example: 'admin@exemple.tn' })
  @IsEmail()
  email: string;

  @ApiProperty({ example: 'Admin2026!', format: 'password' })
  @IsString()
  motDePasse: string;
}

export class JetonDto {
  @ApiProperty({ example: 'eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9…' })
  access_token: string;

  @ApiProperty({ example: 'Bearer' })
  token_type: string;

  @ApiProperty({ example: 900, description: 'Durée de validité en secondes' })
  expires_in: number;
}

@ApiTags('Authentification')
@Controller('auth')
export class AuthController {
  constructor(private readonly jwt: JwtService) {}

  @Public()
  @Post('connexion')
  @HttpCode(200)
  @ApiOperation({ summary: 'Se connecter', description: 'Renvoie un jeton à copier dans le bouton « Authorize ».' })
  @ApiOkResponse({ type: JetonDto })
  @ApiUnauthorizedResponse({ description: 'Identifiants incorrects', type: ErreurDto })
  async connecter(@Body() dto: ConnexionDto): Promise<JetonDto> {
    // Démonstration : un seul compte, sans base de données (voir chapitre 13 pour la vraie version)
    if (dto.email !== 'admin@exemple.tn' || dto.motDePasse !== 'Admin2026!') throw new UnauthorizedException('E-mail ou mot de passe incorrect');
    return { access_token: await this.jwt.signAsync({ sub: 1, role: 'admin' }), token_type: 'Bearer', expires_in: 900 };
  }
}

@Injectable()
export class JwtAuthGuard implements CanActivate {
  constructor(private readonly jwt: JwtService, private readonly reflector: Reflector) {}
  async canActivate(ctx: ExecutionContext) {
    if (this.reflector.getAllAndOverride<boolean>('public', [ctx.getHandler(), ctx.getClass()])) return true;
    const [type, jeton] = (ctx.switchToHttp().getRequest().headers.authorization ?? '').split(' ');
    if (type !== 'Bearer' || !jeton) throw new UnauthorizedException('Jeton manquant');
    ctx.switchToHttp().getRequest().user = await this.jwt.verifyAsync(jeton).catch(() => { throw new UnauthorizedException('Jeton invalide'); });
    return true;
  }
}

📄 src/swagger.ts

import { INestApplication } from '@nestjs/common';
import { DocumentBuilder, SwaggerModule } from '@nestjs/swagger';

export function configurerSwagger(app: INestApplication) {
  const config = new DocumentBuilder()
    .setTitle('API Formation')
    .setDescription('Gestion des stagiaires du centre de formation.\n\n1. `POST /api/auth/connexion` avec le compte de démonstration ;\n2. copiez `access_token` dans **Authorize**.')
    .setVersion('1.0')
    .addBearerAuth()                                   // déclare le schéma de sécurité « bearer » (JWT)
    .addTag('Authentification', 'Connexion et jetons')
    .addTag('Stagiaires', 'Gestion des stagiaires')
    .build();
  const document = SwaggerModule.createDocument(app, config);
  SwaggerModule.setup('docs', app, document, {
    useGlobalPrefix: true,
    jsonDocumentUrl: 'docs/openapi.json',
    customSiteTitle: 'API Formation - documentation',
    swaggerOptions: { persistAuthorization: true, tagsSorter: 'alpha', operationsSorter: 'method' },
  });
  return document;
}

Deux étapes, toutes deux indispensables :

  1. .addBearerAuth() dans DocumentBuilder déclare un schéma de sécurité nommé bearer (HTTP, Bearer, JWT) et fait apparaître le bouton « Authorize ».
  2. @ApiBearerAuth() sur un contrôleur ou une méthode indique que ces routes l'utilisent : Swagger UI affiche un cadenas et envoie l'en-tête Authorization: Bearer … une fois le jeton saisi.

La route de connexion, publique, ne porte pas @ApiBearerAuth(). La documentation décrit la sécurité, elle ne l'applique pas : c'est toujours le guard JWT qui protège les routes.

Le résultat

📄 src/main.ts (script de vérification)

import { ValidationPipe } from '@nestjs/common';
import { NestFactory } from '@nestjs/core';
import { PartialType as PartialTypeMapped } from '@nestjs/mapped-types';
import { SwaggerModule, DocumentBuilder } from '@nestjs/swagger';
import { writeFileSync } from 'node:fs';
import { AppModule } from './app.module';
import { client } from './client';
import { CreerStagiaireDto } from './stagiaires/stagiaire.dto';
import { configurerSwagger } from './swagger';

class ModifierAvecMappedTypes extends PartialTypeMapped(CreerStagiaireDto) {}

async function main() {
  const app = await NestFactory.create(AppModule, { logger: false });
  app.setGlobalPrefix('api');
  app.useGlobalPipes(new ValidationPipe({ whitelist: true, forbidNonWhitelisted: true, transform: true }));
  const doc = configurerSwagger(app);

  console.log('— Opérations documentées');
  for (const [chemin, ops] of Object.entries(doc.paths)) {
    for (const [methode, op] of Object.entries(ops as Record<string, any>)) {
      const verrou = op.security ? '🔒' : '  ';
      console.log(`${verrou} ${methode.toUpperCase().padEnd(6)} ${chemin.padEnd(22)} ${String(op.summary).padEnd(26)} réponses : ${Object.keys(op.responses).join(', ')}`);
    }
  }
  console.log('\n— Schéma de sécurité :', JSON.stringify(doc.components?.securitySchemes));
  console.log('— Schémas :', Object.keys(doc.components?.schemas ?? {}).join(', '));
  console.log('— ModifierStagiaireDto (PartialType de @nestjs/swagger) :', JSON.stringify(doc.components?.schemas?.ModifierStagiaireDto));
  console.log('— Réponse 200 de GET /api/stagiaires :', JSON.stringify((doc.paths['/api/stagiaires'] as any).get.responses['200'].content['application/json'].schema));

  // Même DTO, mais PartialType importé de @nestjs/mapped-types
  const m = await NestFactory.create(AppModule, { logger: false });
  const d2 = SwaggerModule.createDocument(m, new DocumentBuilder().build(), { extraModels: [ModifierAvecMappedTypes] });
  console.log('— PartialType de @nestjs/mapped-types :', JSON.stringify(d2.components?.schemas?.ModifierAvecMappedTypes));

  writeFileSync('openapi.json', JSON.stringify(doc, null, 2));
  console.log('\n— openapi.json écrit (' + JSON.stringify(doc).length + ' caractères)');

  const appel = await client(app);
  console.log('\n— L\'API fonctionne comme avant : la documentation ne change rien au comportement');
  await appel('GET', '/api/stagiaires/1');
  let jeton = '';
  const r = await fetch(`http://localhost:${app.getHttpServer().address().port}/api/auth/connexion`, {
    method: 'POST', headers: { 'content-type': 'application/json' }, body: JSON.stringify({ email: 'admin@exemple.tn', motDePasse: 'Admin2026!' }),
  });
  jeton = (await r.json()).access_token;
  console.log('POST /api/auth/connexion → ' + r.status + ' (jeton reçu)');
  const auth = { Authorization: 'Bearer ' + jeton };
  await appel('GET', '/api/stagiaires?groupe=DEV101', { entetes: auth });
  await appel('POST', '/api/stagiaires', { entetes: auth, corps: { nom: 'S', email: 'pas-un-email', groupe: 'XYZ' } });
  await appel('PATCH', '/api/stagiaires/2', { entetes: auth, corps: { age: 24 } });
  await app.close(); await m.close();
}
main();

Résultat réellement obtenu :

— Opérations documentées
   POST   /api/auth/connexion    Se connecter               réponses : 200, 401
🔒 GET    /api/stagiaires        Lister les stagiaires      réponses : 200, 401
🔒 POST   /api/stagiaires        Inscrire un stagiaire      réponses : 201, 400, 401
🔒 GET    /api/stagiaires/{id}   Consulter un stagiaire     réponses : 200, 401, 404
🔒 PATCH  /api/stagiaires/{id}   Modifier un stagiaire      réponses : 200, 401, 404
🔒 DELETE /api/stagiaires/{id}   Supprimer un stagiaire     réponses : 204, 401, 403

— Schéma de sécurité : {"bearer":{"scheme":"bearer","bearerFormat":"JWT","type":"http"}}
— Schémas : ConnexionDto, JetonDto, ErreurDto, PageDto, Groupe, StagiaireDto, CreerStagiaireDto, ModifierStagiaireDto
— ModifierStagiaireDto (PartialType de @nestjs/swagger) : {"type":"object","properties":{"nom":{"type":"string","description":"Nom complet","example":"Sami Ben Ali","minLength":2,"maxLength":60},"email":{"type":"string","description":"Adresse e-mail (unique)","example":"sami@exemple.tn","format":"email"},"groupe":{"example":"DEV101","allOf":[{"$ref":"#/components/schemas/Groupe"}]},"age":{"type":"integer","minimum":16,"maximum":60,"example":21}}}
— Réponse 200 de GET /api/stagiaires : {"allOf":[{"$ref":"#/components/schemas/PageDto"},{"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/StagiaireDto"}}}}]}
— PartialType de @nestjs/mapped-types : {"type":"object","properties":{}}

— openapi.json écrit (7031 caractères)

— L'API fonctionne comme avant : la documentation ne change rien au comportement
GET /api/stagiaires/1 → 401 {"message":"Jeton manquant","error":"Unauthorized","statusCode":401}
POST /api/auth/connexion → 200 (jeton reçu)
GET /api/stagiaires?groupe=DEV101 → 200 {"data":[{"id":1,"nom":"Sami Ben Ali","email":"sami@exemple.tn","groupe":"DEV101","age":21}],"page":1,"limite":10,"total":1}
POST /api/stagiaires → 400 {"message":["nom must be longer than or equal to 2 characters","email must be an email","groupe must be one of the following values: DEV101, RES201, MM301"],"error":"Bad Request","statusCode":400}
PATCH /api/stagiaires/2 → 200 {"id":2,"nom":"Ines Trabelsi","email":"ines@exemple.tn","groupe":"RES201","age":24}

$ npx openapi-typescript openapi.json -o api.d.ts
🚀 openapi.json → api.d.ts 
        Groupe: "DEV101" | "RES201" | "MM301";
        StagiaireDto: {
            /**
             * @description Nom complet
             * @example Sami Ben Ali
             */
            nom: string;
            /**
             * Format: email
             * @description Adresse e-mail (unique)
             * @example sami@exemple.tn
             */
            email: string;
            /** @example DEV101 */
            groupe: components["schemas"]["Groupe"];
            /** @example 21 */
            age?: number;
            /** @example 1 */
            id: number;
        };
        CreerStagiaireDto: {
            /**
             * @description Nom complet
             * @example Sami Ben Ali
             */
            nom: string;
            /**
             * Format: email
             * @description Adresse e-mail (unique)
             * @example sami@exemple.tn
             */
            email: string;
            /** @example DEV101 */
            groupe: components["schemas"]["Groupe"];
            /** @example 21 */
            age?: number;
        };
        ModifierStagiaireDto: {
Lecture
  • Chaque route a son résumé, ses codes de réponse, et un cadenas 🔒 sauf la connexion.
  • Le schéma de sécurité bearer est déclaré une fois dans components.securitySchemes.
  • ModifierStagiaireDto (PartialType de @nestjs/swagger) garde descriptions, exemples et contraintes, sans required: tout est facultatif. Le même DTO construit avec PartialType de @nestjs/mapped-types a un schéma vide: l'erreur est silencieuse, le code compile et fonctionne, seule la documentation est fausse.
  • La réponse de la liste est bien « PageDto + data: StagiaireDto[] ».
  • L'API se comporte exactement comme avant : les décorateurs @Api… n'ont aucun effet sur l'exécution, seulement sur le document.
  • Dernière étape : openapi-typescript transforme le document en types TypeScript utilisables par le client Angular (chapitre 18).
Dans Swagger UI

Détail de la route POST /api/stagiaires dans Swagger UI

Le corps attendu est rempli avec les exemples des @ApiProperty ; chaque code de réponse a sa description et son schéma.

Observez les exemples des réponses 400 et 401 : ils affichent 404 et « Stagiaire 9 introuvable », car ErreurDto n'a qu'un exemple, celui de la 404. Le document est exact (la forme est la bonne), mais l'exemple induit en erreur. L'activité 2 corrige ce défaut.

Fenêtre Authorize de Swagger UI

Le bouton « Authorize » ouvre cette fenêtre : on y colle le jeton (sans le mot Bearer).

Essai de la route de connexion dans Swagger UI

« Try it out » puis « Execute » sur la route de connexion : la requête curl équivalente, puis la réponse réelle de l'API avec le jeton.

Le parcours complet pour un utilisateur de la documentation : exécuter POST /api/auth/connexion, copier access_token, cliquer sur « Authorize », coller le jeton, valider. Toutes les routes à cadenas sont alors appelées avec le jeton ; grâce à persistAuthorization, il reste en place après un rechargement de la page.

Bonnes pratiques

  • Documentez toutes les réponses d'erreur qu'une route peut réellement renvoyer, pas seulement le succès.
  • Donnez des exemples réalistes : c'est ce que le développeur front copie en premier.
  • Activez le plugin pour les propriétés simples, gardez les décorateurs pour les cas que le plugin ne peut pas deviner (génériques, énumérations nommées, exemples précis, réponses d'erreur).
  • Vérifiez régulièrement le document : un test peut comparer openapi.json à la version précédente pour détecter un changement de contrat involontaire (chapitre 17).
Activités

Activité 1 Documenter un contrôleur

Documentez GroupesController du TP 8 : tag, opérations, paramètres, réponses (y compris 400, 403 et 404) et @ApiBearerAuth(). Créez un GroupeDto de sortie avec @ApiProperty et des exemples.

Voir le corrigé
@ApiTags('Groupes')
@ApiBearerAuth()
@ApiUnauthorizedResponse({ type: ErreurDto })
@Controller('groupes')
export class GroupesController {
  @Post()
  @Roles(Role.Admin)
  @ApiOperation({ summary: 'Créer un groupe', description: 'Réservé aux administrateurs.' })
  @ApiCreatedResponse({ type: GroupeDto })
  @ApiBadRequestResponse({ description: 'Données invalides ou formateur inexistant', type: ErreurDto })
  @ApiForbiddenResponse({ description: 'Rôle insuffisant', type: ErreurDto })
  creer(@Body() dto: CreerGroupeDto): Promise<GroupeDto> { … }
}

Activité 2 Des exemples d'erreur justes

Corrigez le défaut observé dans la capture : la réponse 401 doit montrer un exemple 401 / Jeton manquant / Unauthorized et la 400 un tableau de messages de validation. Utilisez l'option example des décorateurs de réponse.

Voir le corrigé
@ApiUnauthorizedResponse({
  description: 'Jeton absent, invalide ou expiré',
  type: ErreurDto,
  example: { statusCode: 401, message: 'Jeton manquant', error: 'Unauthorized' },
})
@ApiBadRequestResponse({
  description: 'Données invalides',
  type: ErreurDto,
  example: { statusCode: 400, message: ['email must be an email'], error: 'Bad Request' },
})

Pour éviter de répéter ces blocs, regroupez-les dans des décorateurs composés (ApiErreur401(), ApiErreur400()) avec applyDecorators, comme ApiPageResponse. Vérifiez le résultat dans Swagger UI.

Activité 3 Corriger les types utilitaires

Recherchez dans votre projet les imports from '@nestjs/mapped-types'. Remplacez-les par @nestjs/swagger et comparez le schéma de vos DTO de modification dans /api/docs-json avant et après. Faut-il garder @nestjs/mapped-types dans package.json?

Voir le corrigé

Avant : schéma vide (properties: {}), comme dans le résultat de la leçon. Après : toutes les propriétés, facultatives. @nestjs/swagger fournit les mêmes fonctions avec le même comportement de validation : @nestjs/mapped-types peut être désinstallé s'il n'est plus importé nulle part.

Activité 4 Synthèse : documenter l'API du TP 8

Documentez entièrement votre projet api-scolarite-securisee: configuration dans src/swagger.ts, activée hors production ; plugin activé ; tags Authentification, Utilisateurs, Groupes, Notes ; routes publiques sans cadenas ; réponses d'erreur avec exemples justes ; openapi.json généré par un script et versionné. Mettez à jour le README (lien vers /api/docs), faites un commit docs: documentation OpenAPI et poussez sur GitHub.

Voir le corrigé

Points de contrôle : la connexion fonctionne depuis Swagger UI et le jeton permet d'appeler les routes protégées ; un stagiaire connecté reçoit bien 403 sur les routes d'administration (la documentation ne change pas les droits) ; aucune route n'a un schéma vide ; NODE_ENV=production supprime /api/docs. Bonus : générez api.d.ts avec npx openapi-typescript openapi.json -o api.d.ts pour le client Angular du chapitre 18.

À retenir

  • DTO : @ApiProperty / @ApiPropertyOptional (description, example, enum + enumName, format, minimum…).
  • PartialType, PickType, OmitType : à importer de @nestjs/swagger, sinon le schéma est vide.
  • Routes : @ApiTags, @ApiOperation, @ApiParam, @ApiQuery, @ApiOkResponse / @ApiCreatedResponse / @Api…Response({ type }).
  • Génériques : ApiExtraModels + getSchemaPath dans un décorateur composé.
  • JWT : .addBearerAuth() déclare, @ApiBearerAuth() applique ; bouton Authorize, persistAuthorization.
  • Les décorateurs @Api… décrivent sans rien changer à l'exécution ; le document alimente aussi la génération de types.

Cet article vous a-t-il aidé ?