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

Présentation de Swagger et de la spécification OpenAPI

Cette leçon présente la documentation d'une API REST. Elle distingue OpenAPI, la spécification qui décrit une API dans un fichier JSON ou YAML, et Swagger, la famille d'outils qui l'exploitent : Swagg...

0 chapitres 0 QCM Accès gratuit
Présentation de Swagger et de la spécification OpenAPI

À propos de ce cours

Cette leçon présente la documentation d'une API REST. Elle distingue OpenAPI, la spécification qui décrit une API dans un fichier JSON ou YAML, et Swagger, la famille d'outils qui l'exploitent : Swagger UI, Editor et Codegen. La structure d'un document OpenAPI 3 est détaillée : info, servers, tags, paths, components. Un document réellement généré par NestJS à partir d'un contrôleur montre ce que le framework devine seul, et ce qui manque encore, comme les propriétés des DTO. La leçon compare les approches code-first et design-first et cite les autres outils. Activités corrigées.

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

OpenAPI et l'écosystème Swagger

Le document OpenAPI est au centre : il est produit à partir du code et exploité par de nombreux outils.

OpenAPISwagger
Natureune spécification: le format d'un document qui décrit une API RESTune famille d'outils qui lisent ou produisent ce format
ExemplesOpenAPI 3.0 (2017), 3.1 (2021)Swagger UI, Swagger Editor, Swagger Codegen
GouvernanceOpenAPI 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 }
SectionContenu
openapila version de la spécification utilisée
infotitre, description, version de votre API, contact, licence
serversles URL de base (développement, production)
tagsles groupes de routes (Stagiaires, Authentification…)
pathschaque chemin, chaque méthode HTTP : paramètres (path, query, header), corps (requestBody), réponses par code de statut
componentsles é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 type number (grâce à ParseIntPipe et 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 contient nom, 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émarcheon écrit le code, le document en est déduiton écrit le document OpenAPI, puis on code pour le respecter
Avantagela documentation suit toujours le codele front et le back travaillent en parallèle sur un contrat validé
Risqueune API « telle qu'elle est codée », sans réflexion de conceptionun document et un code qui divergent si rien ne les vérifie
Pour quipetites équipes, projets internes, ce coursgrandes é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é ?