À propos de ce cours
Objectifs de la leçon
- Expliquer pourquoi une API doit être documentée.
- Distinguer OpenAPI (la spécification) et Swagger (les outils).
- Lire la structure d'un document OpenAPI 3.
- Comparer les approches code-first et design-first.
Pourquoi documenter une API ?
Une API n'a pas d'interface graphique : ceux qui l'utilisent (le développeur Angular du chapitre 18, une application mobile, un partenaire, vous-même dans six mois) doivent savoir quelles routes existent, quels paramètres et quel corps envoyer, quelles réponses et quelles erreurs attendre, et comment s'authentifier.
Un document Word ou un README écrit à la main devient vite faux : une route est ajoutée, un champ renommé, et personne ne met la documentation à jour. La solution moderne : une description de l'API dans un format standard, lisible par les machines, et générée autant que possible à partir du code lui-même.
OpenAPI et Swagger
Le document OpenAPI est au centre : il est produit à partir du code et exploité par de nombreux outils.
| OpenAPI | Swagger | |
|---|---|---|
| Nature | une spécification: le format d'un document qui décrit une API REST | une famille d'outils qui lisent ou produisent ce format |
| Exemples | OpenAPI 3.0 (2017), 3.1 (2021) | Swagger UI, Swagger Editor, Swagger Codegen |
| Gouvernance | OpenAPI Initiative (Linux Foundation) | SmartBear (entreprise) |
Historiquement, la spécification s'appelait elle-même « Swagger » (jusqu'à Swagger 2.0). Elle a été renommée OpenAPI en 2016, lors de son passage à une fondation. On parle encore souvent de « la doc Swagger » pour désigner la page interactive : c'est le nom de l'outil d'affichage, Swagger UI.
- Swagger UI: une page web qui affiche le document et permet d'essayer chaque route (bouton « Try it out »). C'est elle que NestJS servira à la leçon 14.2.
- Swagger Editor (editor.swagger.io) : un éditeur en ligne pour écrire un document à la main, avec l'aperçu à côté.
- Codegen et ses équivalents (openapi-generator, openapi-typescript) : générer des clients (TypeScript, Java, Dart…) ou des types à partir du document (leçon 14.3).
La structure d'un document OpenAPI 3
Voici un document minimal, écrit à la main en YAML, qui décrit une seule route :
openapi: 3.0.3
info:
title: API Formation
version: '1.0'
paths:
/api/stagiaires/{id}:
get:
summary: Consulter un stagiaire
tags: [Stagiaires]
parameters:
- name: id
in: path
required: true
schema: { type: integer, example: 1 }
responses:
'200':
description: Le stagiaire
content:
application/json:
schema: { $ref: '#/components/schemas/Stagiaire' }
'404':
description: Stagiaire introuvable
components:
schemas:
Stagiaire:
type: object
required: [id, nom, email]
properties:
id: { type: integer, example: 1 }
nom: { type: string, example: Sami Ben Ali }
email: { type: string, format: email }
| Section | Contenu |
|---|---|
openapi | la version de la spécification utilisée |
info | titre, description, version de votre API, contact, licence |
servers | les URL de base (développement, production) |
tags | les groupes de routes (Stagiaires, Authentification…) |
paths | chaque chemin, chaque méthode HTTP : paramètres (path, query, header), corps (requestBody), réponses par code de statut |
components | les éléments réutilisables : schemas (la forme des objets, en JSON Schema), securitySchemes (JWT, clé API…) |
$ref: '#/components/schemas/Stagiaire' est une référence: le schéma est décrit une fois et réutilisé partout. Les DTO de NestJS deviendront ces schémas.
Ce que NestJS sait déjà de votre API
Avec NestJS, on n'écrit pas ce YAML : @nestjs/swagger parcourt les contrôleurs et produit le document. Prenons le contrôleur du chapitre 08 (un CreerStagiaireDto validé par class-validator), sans aucune annotation Swagger, et affichons le document généré :
npm install @nestjs/swagger
📄 src/stagiaire.dto.ts
import { IsEmail, IsIn, IsInt, IsOptional, IsString, Length, Max, Min } from 'class-validator';
export class CreerStagiaireDto {
@IsString()
@Length(2, 60)
nom: string;
@IsEmail()
email: string;
@IsIn(['DEV101', 'RES201', 'MM301'])
groupe: string;
@IsOptional()
@IsInt()
@Min(16)
@Max(60)
age?: number;
}
📄 src/stagiaires.controller.ts
import { Body, Controller, Get, NotFoundException, Param, ParseIntPipe, Post } from '@nestjs/common';
import { CreerStagiaireDto } from './stagiaire.dto';
@Controller('stagiaires')
export class StagiairesController {
private stagiaires: (CreerStagiaireDto & { id: number })[] = [{ id: 1, nom: 'Sami Ben Ali', email: 'sami@exemple.tn', groupe: 'DEV101', age: 21 }];
@Get()
lister() {
return this.stagiaires;
}
@Get(':id')
trouver(@Param('id', ParseIntPipe) id: number) {
const s = this.stagiaires.find((x) => x.id === id);
if (!s) throw new NotFoundException(`Stagiaire ${id} introuvable`);
return s;
}
@Post()
creer(@Body() dto: CreerStagiaireDto) {
const s = { id: this.stagiaires.length + 1, ...dto };
this.stagiaires.push(s);
return s;
}
}
📄 src/main.ts
import { NestFactory } from '@nestjs/core';
import { DocumentBuilder, SwaggerModule } from '@nestjs/swagger';
import { AppModule } from './app.module';
async function main() {
const app = await NestFactory.create(AppModule, { logger: false });
app.setGlobalPrefix('api');
const config = new DocumentBuilder().setTitle('API Formation').setVersion('1.0').build();
const document = SwaggerModule.createDocument(app, config);
// Le document est un simple objet JavaScript, sérialisable en JSON ou en YAML
console.log('openapi :', document.openapi);
console.log('info :', JSON.stringify(document.info));
console.log('chemins :');
for (const [chemin, operations] of Object.entries(document.paths)) {
console.log(' ' + chemin.padEnd(20), Object.keys(operations).join(', ').toUpperCase());
}
console.log('\nL\'opération GET /api/stagiaires/{id} :');
console.log(JSON.stringify(document.paths['/api/stagiaires/{id}'].get, null, 2));
console.log('\nLe schéma du DTO :');
console.log(JSON.stringify(document.components?.schemas?.CreerStagiaireDto, null, 2));
await app.close();
}
main();
Résultat réellement obtenu :
openapi : 3.0.0
info : {"title":"API Formation","description":"","version":"1.0","contact":{}}
chemins :
/api/stagiaires GET, POST
/api/stagiaires/{id} GET
L'opération GET /api/stagiaires/{id} :
{
"operationId": "StagiairesController_trouver",
"parameters": [
{
"name": "id",
"required": true,
"in": "path",
"schema": {
"type": "number"
}
}
],
"responses": {
"200": {
"description": ""
}
},
"tags": [
"Stagiaires"
]
}
Le schéma du DTO :
{
"type": "object",
"properties": {}
}
Lecture
- Ce que NestJS devine: les chemins (avec le préfixe global
/api), les méthodes, le paramètre{id}de typenumber(grâce àParseIntPipeet au type TypeScript), un identifiant d'opération (StagiairesController_trouver) et un tag tiré du nom du contrôleur. - Ce qui manque: le schéma du DTO est vide (
"properties": {}). À l'exécution, TypeScript a effacé les types des propriétés : NestJS ne sait pas que le corps contientnom,email,groupe. Les réponses n'ont pas de description ni de schéma, la 404 n'est pas mentionnée.
Les deux leçons suivantes comblent ces manques : le plugin de la CLI ou les décorateurs @ApiProperty pour les DTO, et les décorateurs @ApiOperation, @ApiResponse… pour les routes.
Code-first ou design-first ?
| Code-first (NestJS + @nestjs/swagger) | Design-first (contrat d'abord) | |
|---|---|---|
| Démarche | on écrit le code, le document en est déduit | on écrit le document OpenAPI, puis on code pour le respecter |
| Avantage | la documentation suit toujours le code | le front et le back travaillent en parallèle sur un contrat validé |
| Risque | une API « telle qu'elle est codée », sans réflexion de conception | un document et un code qui divergent si rien ne les vérifie |
| Pour qui | petites équipes, projets internes, ce cours | grandes équipes, API publiques, partenaires |
Les deux se combinent : on conçoit les routes et les DTO avec soin (chapitres 06 et 08), et le document généré sert de contrat partagé avec l'équipe front.
Autres affichages du même document : Redoc (lecture seule, très lisible), Scalar (interface moderne avec essais), ou l'import dans Postman ou Insomnia, qui transforment le document en collection de requêtes. Tous lisent le même fichier OpenAPI : c'est l'intérêt d'un standard.
Activités
Activité 1 Lire un document
Dans le YAML de la leçon : (a) quelle est l'URL complète pour consulter le stagiaire 7 ? (b) Quels champs sont obligatoires dans la réponse ? (c) Que reçoit le client si le stagiaire n'existe pas, et que manque-t-il pour le savoir précisément ?
Voir le corrigé
(a) /api/stagiaires/7, préfixée par l'URL d'un serveur (servers, absent ici). (b) id, nom, email (required). (c) Un statut 404 ; mais la forme du corps de l'erreur n'est pas décrite (pas de content) : le client ne sait pas qu'il recevra statusCode, message, error. La leçon 14.3 ajoute un schéma ErreurDto.
Activité 2 Écrire à la main
Ouvrez editor.swagger.io, collez le YAML de la leçon et ajoutez l'opération POST /api/stagiaires avec un corps CreerStagiaire (nom, email, groupe parmi DEV101, RES201, MM301) et les réponses 201 et 400. Observez l'aperçu à droite.
Voir le corrigé
/api/stagiaires:
post:
summary: Inscrire un stagiaire
tags: [Stagiaires]
requestBody:
required: true
content:
application/json:
schema: { $ref: '#/components/schemas/CreerStagiaire' }
responses:
'201':
description: Stagiaire créé
content:
application/json:
schema: { $ref: '#/components/schemas/Stagiaire' }
'400':
description: Données invalides
# dans components.schemas :
CreerStagiaire:
type: object
required: [nom, email, groupe]
properties:
nom: { type: string, minLength: 2, maxLength: 60 }
email: { type: string, format: email }
groupe: { type: string, enum: [DEV101, RES201, MM301] }
Vous mesurez le travail que NestJS va vous épargner : avec le plugin de la leçon 14.2, ce schéma est déduit du DTO et de ses règles class-validator.
Activité 3 Repérer les manques
Exécutez le script de la leçon sur votre projet du chapitre 08 (ou du TP 5). Listez trois informations utiles à un développeur front qui n'apparaissent pas dans le document généré.
Voir le corrigé
Par exemple : les propriétés des DTO (schéma vide) ; la forme des réponses (aucun schéma de sortie) ; les erreurs possibles (400, 404, 409) ; une description en français de chaque route ; des exemples de valeurs ; le fait qu'une route exige un jeton (chapitre 13).
Activité 4 Choisir une démarche
Pour chaque situation, code-first ou design-first ? (a) Vous développez seul l'API de votre projet de fin de formation. (b) Une banque publie une API pour ses partenaires, et trois équipes doivent l'implémenter. (c) L'équipe Angular doit commencer l'interface avant que l'API existe.
Voir le corrigé
(a) Code-first : rapide, la documentation suit le code. (b) Design-first : le contrat est négocié et validé avant d'écrire le code ; il sert de référence aux trois équipes. (c) Design-first, ou au moins un document écrit tôt : l'équipe Angular peut générer des types et même un serveur simulé (mock) à partir du contrat.
À retenir
- OpenAPI = la spécification (JSON/YAML) qui décrit une API ; Swagger = les outils (UI, Editor, Codegen).
- Un document OpenAPI 3 : info, servers, tags, paths (paramètres, corps, réponses), components (schemas, securitySchemes).
- @nestjs/swagger génère le document à partir des contrôleurs : approche code-first.
- Sans aide, les propriétés des DTO et les réponses ne sont pas connues : il faut le plugin ou les décorateurs @Api….
- Un même document alimente Swagger UI, Redoc, Postman, la génération de clients.
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 !