À propos de ce cours
Objectifs de la leçon
- Installer et configurer @nestjs/swagger.
- Publier Swagger UI et le document JSON/YAML.
- Désactiver la documentation en production.
- Activer le plugin de la CLI pour documenter les DTO automatiquement.
Versions: ce chapitre a été exécuté avec NestJS 12.5 et @nestjs/swagger 12.1 (projet créé avec nest new en choisissant CommonJS), puis vérifié avec NestJS 11.2 et @nestjs/swagger 11.4 : les résultats sont identiques.
Sur un projet NestJS 11, npm install @nestjs/swagger échoue avec ERESOLVE (la version 12 exige NestJS 12) : installez npm install @nestjs/swagger@11. Vérifiez votre version avec npm ls @nestjs/core.
Installation et configuration
npm install @nestjs/swagger
DocumentBuilder décrit l'API, createDocument parcourt l'application, setup publie le résultat.
📄 src/app.ts (le main.ts de votre projet)
import { ValidationPipe } from '@nestjs/common';
import { NestFactory } from '@nestjs/core';
import { DocumentBuilder, SwaggerModule } from '@nestjs/swagger';
import { AppModule } from './app.module';
async function bootstrap() {
const app = await NestFactory.create(AppModule);
app.setGlobalPrefix('api');
app.useGlobalPipes(new ValidationPipe({ whitelist: true, transform: true }));
if (process.env.NODE_ENV !== 'production') {
const config = new DocumentBuilder()
.setTitle('API Formation')
.setDescription('Gestion des stagiaires et des groupes du centre de formation')
.setVersion('1.0')
.addServer('http://localhost:3000', 'Développement')
.build();
const documentFactory = () => SwaggerModule.createDocument(app, config);
SwaggerModule.setup('docs', app, documentFactory, {
useGlobalPrefix: true, // → /api/docs (sinon /docs)
jsonDocumentUrl: 'docs/openapi.json', // → /api/docs/openapi.json
customSiteTitle: 'API Formation - documentation',
});
}
await app.listen(process.env.PORT ?? 3000);
}
bootstrap();
DocumentBuilderconstruit la partieinfoetserversdu document (leçon 14.1). On y ajoutera la sécurité à la leçon 14.3.SwaggerModule.createDocument(app, config)parcourt les modules, contrôleurs et DTO de l'application. On le passe ici sous forme de fabrique (documentFactory) : le document n'est construit qu'au moment où la page est demandée pour la première fois.SwaggerModule.setup(chemin, app, document, options)publie Swagger UI. Par défaut, le chemin ignore le préfixe global :useGlobalPrefix: truele place sous/api.- Le
ifsurNODE_ENV(chapitre 10) n'active la documentation qu'en dehors de la production.
Le programme suivant démarre cette application deux fois, en développement puis en production, et interroge plusieurs URL :
📄 src/main.ts (script de vérification)
import { spawn } from 'node:child_process';
// Démarre l'application (dist/app.js) avec un environnement donné, puis interroge quelques URL
async function essayer(env: Record<string, string>, urls: string[]) {
const proc = spawn('node', ['dist/app.js'], { env: { ...process.env, ...env } });
await new Promise((r) => setTimeout(r, 1500));
for (const url of urls) {
const r = await fetch('http://localhost:' + env.PORT + url);
const texte = await r.text();
const apercu = texte.replace(/\s+/g, ' ').slice(0, 90);
console.log(`GET ${url} → ${r.status} ${r.headers.get('content-type')?.split(';')[0]} | ${apercu}…`);
}
proc.kill();
}
async function main() {
console.log('— NODE_ENV=development');
await essayer({ NODE_ENV: 'development', PORT: '3101' },
['/api/docs', '/api/docs/openapi.json', '/api/docs-yaml', '/docs', '/api/stagiaires']);
console.log('\n— NODE_ENV=production');
await essayer({ NODE_ENV: 'production', PORT: '3102' }, ['/api/docs', '/api/docs/openapi.json', '/api/stagiaires']);
}
main();
Résultat réellement obtenu :
— NODE_ENV=development
GET /api/docs → 200 text/html | <!-- HTML for static distribution bundle build --> <!DOCTYPE html> <html lang="en"> <head…
GET /api/docs/openapi.json → 200 application/json | {"openapi":"3.0.0","paths":{"/api/stagiaires":{"get":{"operationId":"StagiairesController_…
GET /api/docs-yaml → 200 text/yaml | openapi: 3.0.0 paths: /api/stagiaires: get: operationId: StagiairesController_lister param…
GET /docs → 404 text/html | <!DOCTYPE html> <html lang="en"> <head> <meta charset="utf-8"> <title>Error</title> </head…
GET /api/stagiaires → 200 application/json | [{"id":1,"nom":"Sami Ben Ali","email":"sami@exemple.tn","groupe":"DEV101","age":21}]…
— NODE_ENV=production
GET /api/docs → 404 application/json | {"message":"Cannot GET /api/docs","error":"Not Found","statusCode":404}…
GET /api/docs/openapi.json → 404 application/json | {"message":"Cannot GET /api/docs/openapi.json","error":"Not Found","statusCode":404}…
GET /api/stagiaires → 200 application/json | [{"id":1,"nom":"Sami Ben Ali","email":"sami@exemple.tn","groupe":"DEV101","age":21}]…
Lecture
/api/docs: la page Swagger UI (HTML). Les fichiers de l'interface sont servis par l'application elle-même, sans connexion à Internet./api/docs/openapi.json: le document JSON, à l'URL choisie avecjsonDocumentUrl(par défautdocs-json)./api/docs-yaml: le même document en YAML. C'est ce fichier que l'on importe dans Postman ou que l'on donne à un générateur de client./docssans préfixe : 404, à cause deuseGlobalPrefix: true.- En production, aucune de ces URL n'existe, mais l'API fonctionne normalement.

Swagger UI tel qu'il s'affiche dans le navigateur (version complète de la leçon 14.3) : titre, description, bouton Authorize, routes groupées par tag, schémas.
Faut-il publier la documentation en production ? Pour une API interne, non : elle donne à un attaquant la liste exacte de vos routes et de vos paramètres. Pour une API publique destinée à des partenaires, oui, mais en connaissance de cause : routes d'administration masquées (@ApiExcludeController() ou @ApiExcludeEndpoint()), voire page protégée par un mot de passe. La documentation ne remplace jamais la sécurité : une route cachée doit rester protégée par ses guards.
Options utiles de SwaggerModule.setup
| Option | Effet |
|---|---|
useGlobalPrefix | applique le préfixe global (/api/docs) |
jsonDocumentUrl, yamlDocumentUrl | URL du document JSON et YAML |
customSiteTitle | titre de l'onglet du navigateur |
swaggerOptions.persistAuthorization | garde le jeton saisi dans « Authorize » après un rechargement (leçon 14.3) |
swaggerOptions.tagsSorter, operationsSorter | tri des groupes et des routes ('alpha', 'method') |
ui: false, raw: ['json'] | ne publier que le document, ou seulement certains formats |
Le plugin de la CLI : documenter les DTO sans effort
À la leçon 14.1, le schéma du DTO était vide. On peut le décrire propriété par propriété avec @ApiProperty (leçon 14.3), ou laisser le plugin de @nestjs/swagger le faire à la compilation. Il s'active dans nest-cli.json:
📄 nest-cli.json
{
"$schema": "https://json.schemastore.org/nest-cli",
"collection": "@nestjs/schematics",
"sourceRoot": "src",
"compilerOptions": {
"deleteOutDir": true,
"plugins": [
{
"name": "@nestjs/swagger",
"options": { "classValidatorShim": true, "introspectComments": true }
}
]
}
}
Le même DTO, avec quelques commentaires JSDoc (/** … */) :
📄 src/stagiaire.dto.ts
import { IsEmail, IsIn, IsInt, IsOptional, IsString, Length, Max, Min } from 'class-validator';
export class CreerStagiaireDto {
/**
* Nom complet du stagiaire
* @example 'Sami Ben Ali'
*/
@IsString()
@Length(2, 60)
nom: string;
/** Adresse e-mail, unique */
@IsEmail()
email: string;
/** Code du groupe */
@IsIn(['DEV101', 'RES201', 'MM301'])
groupe: string;
@IsOptional()
@IsInt()
@Min(16)
@Max(60)
age?: number;
}
Compilons le projet avec nest build, sans puis avec le plugin, et affichons le schéma généré :
Sans le plugin :
$ nest build (sans plugin)
{
"type": "object",
"properties": {}
}
Réponse de GET /api/stagiaires/{id} : {"description":""}
Avec le plugin :
$ nest build (avec le plugin @nestjs/swagger)
{
"type": "object",
"properties": {
"nom": {
"type": "string",
"description": "Nom complet du stagiaire",
"example": "Sami Ben Ali",
"minLength": 2,
"maxLength": 60
},
"email": {
"type": "string",
"description": "Adresse e-mail, unique",
"format": "email"
},
"groupe": {
"type": "string",
"description": "Code du groupe",
"enum": [
"DEV101",
"RES201",
"MM301"
]
},
"age": {
"type": "number",
"minimum": 16,
"maximum": 60
}
},
"required": [
"nom",
"email",
"groupe"
]
}
Réponse de GET /api/stagiaires/{id} : {"description":"","content":{"application/json":{"schema":{"type":"object"}}}}
Ce que fait le plugin
- Il lit les types TypeScript des propriétés avant qu'ils soient effacés :
string,number, etage?optionnel (absent derequired). - Avec
classValidatorShim, il traduit les règles class-validator :@Length(2, 60)→minLength/maxLength,@IsEmail()→format: email,@IsIn→enum,@Min/@Max→minimum/maximum. - Avec
introspectComments, le commentaire devient ladescription, et@examplel'exemple affiché dans Swagger UI. - Il déduit aussi le type de retour des méthodes : la réponse 200 a maintenant un contenu JSON (ici un simple
object, faute de type de retour déclaré).
Conditions de fonctionnement du plugin
- Il agit pendant la compilation par la CLI :
nest build,nest start,nest start --watch. Une compilation directe avectscne l'applique pas (c'est le cas du script de la leçon 14.1). - Il n'analyse que les fichiers dont le nom se termine par
.dto.tsou.entity.ts(optiondtoFileNameSuffix) : respectez les conventions de nommage denest g. - Il ne remplace pas les décorateurs quand on veut un exemple précis, une énumération nommée ou un schéma de réponse : les deux se combinent, le décorateur l'emporte.
Organiser le code
Pour ne pas surcharger main.ts, on place la configuration dans un fichier src/swagger.ts exportant une fonction configurerSwagger(app), appelée depuis main.ts. C'est la forme utilisée à la leçon 14.3.
Activités
Activité 1 Mettre en place Swagger
Dans votre projet du TP 8, installez @nestjs/swagger, publiez la documentation sur /api/docs avec le titre « API Scolarité », une description et la version lue dans package.json. Vérifiez /api/docs et /api/docs-json. Pourquoi le navigateur affiche-t-il une page même si la route /api/docs n'est déclarée dans aucun contrôleur ?
Voir le corrigé
const config = new DocumentBuilder()
.setTitle('API Scolarité')
.setDescription('Comptes, groupes et notes du centre de formation')
.setVersion(process.env.npm_package_version ?? '1.0') // fournie par npm (npm run start:dev)
.build();
SwaggerModule.setup('docs', app, () => SwaggerModule.createDocument(app, config), { useGlobalPrefix: true });
SwaggerModule.setup enregistre directement des routes auprès du serveur Express sous-jacent (page HTML, fichiers de Swagger UI, JSON, YAML). Elles ne passent pas par les contrôleurs : c'est pourquoi le guard JWT global du TP 8 ne les protège pas.
Activité 2 Activer selon la configuration
Remplacez le test sur NODE_ENV par une variable SWAGGER_ACTIF (booléen, true par défaut en développement), lue avec ConfigService et validée dans le schéma de configuration (chapitre 10).
Voir le corrigé
// main.ts
const config = app.get(ConfigService);
if (config.get<boolean>('SWAGGER_ACTIF')) configurerSwagger(app);
// schéma Joi (chapitre 10)
SWAGGER_ACTIF: Joi.boolean().default(false), // et SWAGGER_ACTIF=true dans .env.development
Activité 3 Exporter le document
Écrivez un script npm run openapi qui génère le fichier openapi.json à la racine du projet sans démarrer le serveur HTTP. À quoi sert ce fichier versionné dans le dépôt GitHub ?
Voir le corrigé
// src/generer-openapi.ts
import { NestFactory } from '@nestjs/core';
import { writeFileSync } from 'node:fs';
import { AppModule } from './app.module';
import { configurerSwagger } from './swagger';
async function generer() {
const app = await NestFactory.create(AppModule, { logger: false });
app.setGlobalPrefix('api');
writeFileSync('openapi.json', JSON.stringify(configurerSwagger(app), null, 2));
await app.close(); // app.listen() n'est jamais appelé
}
generer();
// package.json : "openapi": "nest build && node dist/generer-openapi.js"
Versionné, le document permet de voir dans chaque pull request si le contrat de l'API change (route supprimée, champ renommé), de générer les types du client Angular et de l'importer dans Postman. Attention : si l'application se connecte à la base au démarrage, le script en a besoin aussi.
Activité 4 Le plugin à l'épreuve
Activez le plugin dans votre projet. Renommez un fichier creer-groupe.dto.ts en creer-groupe.ts: que devient son schéma dans /api/docs-json? Ajoutez un commentaire /** … @example … */ sur une propriété et vérifiez son affichage dans Swagger UI.
Voir le corrigé
Sans le suffixe .dto.ts, le plugin ignore le fichier : le schéma redevient vide (properties: {}). Le commentaire apparaît comme description de la propriété et l'exemple est utilisé dans « Example Value ». Pensez à relancer nest start: le plugin agit à la compilation.
À retenir
- npm install @nestjs/swagger (version 12 pour NestJS 12, @11 pour un projet NestJS 11).
- DocumentBuilder (titre, description, version, serveurs) → SwaggerModule.createDocument → SwaggerModule.setup('docs', app, …).
- useGlobalPrefix: true → /api/docs ; JSON sur /api/docs-json (ou jsonDocumentUrl), YAML sur /api/docs-yaml.
- Documentation désactivée en production (NODE_ENV ou variable dédiée) : elle révèle toutes vos routes.
- Plugin dans nest-cli.json : types, règles class-validator et commentaires des fichiers .dto.ts, avec nest build / nest start.
Cet article vous a-t-il aidé ?
Merci pour votre avis sur cet article 🙏
Merci, votre message nous a bien été transmis 🙏
Cette leçon vous a été utile ? Partagez-la !