Chroniques de l'Empire : Introduction à la documentation d'API

Salve, chroniqueur de l'Empire ! Bienvenue dans l'une des missions les plus importantes de notre Empire - la création des Chroniques de l'API. Tout comme les anciens Romains documentaient méticuleusement leurs lois, leurs décrets impériaux et l'organisation des légions dans les Annales de l'Empire, nous allons documenter notre API à l'aide de Swagger et d'OpenAPI.

Qu'est-ce qu'OpenAPI ?

OpenAPI (anciennement connu sous le nom de Swagger Specification) est une spécification standard pour décrire les interfaces d'API REST. Considère-la comme la langue administrative officielle de l'Empire - une manière unifiée de communiquer entre les provinces.

La spécification OpenAPI définit la structure de l'API au format JSON ou YAML :

1// Voici à quoi ressemble la description d'un endpoint au format OpenAPI
2{
3  "paths": {
4    "/legiones": {
5      "get": {
6        "summary": "Get list of legions",
7        "description": "Returns all legions of the Empire",
8        "responses": {
9          "200": {
10            "description": "List of legions"
11          }
12        }
13      }
14    }
15  }
16}

Qu'est-ce que Swagger ?

Swagger est un ensemble d'outils pour travailler avec la spécification OpenAPI. Dans le contexte de NestJS, le plus important est Swagger UI - une page de documentation interactive qui permet de parcourir et de tester les endpoints de l'API directement depuis le navigateur.

Swagger UI est comme le Forum Romanum de notre API - un lieu où chaque citoyen (développeur) peut voir les services disponibles de l'Empire, les tester et comprendre comment ils fonctionnent.

Pourquoi la documentation d'API est-elle importante ?

Tout comme l'Empire romain ne pouvait pas fonctionner sans lois et décrets écrits, les API modernes ne devraient pas exister sans documentation :

1. Communication entre les équipes - le frontend et le backend parlent la même langue
2. Intégration des nouveaux développeurs - les nouveaux légionnaires apprennent rapidement la structure de l'API
3. Tests - Swagger UI permet de tester les endpoints sans écrire de code
4. Génération de code client - génération automatique du SDK à partir de la spécification
5. Contrats d'API - un accord clair entre le fournisseur et le consommateur de l'API

@nestjs/swagger - Le Scribe de l'Empire

Dans NestJS, nous utilisons le paquet @nestjs/swagger pour créer la documentation. Ce paquet génère automatiquement la spécification OpenAPI à partir des décorateurs présents dans notre code :

1import { Controller, Get } from '@nestjs/common';
2import { ApiTags, ApiOperation, ApiResponse } from '@nestjs/swagger';
3
4@ApiTags('Legiones')
5@Controller('legiones')
6export class LegionController {
7  @ApiOperation({ summary: 'Get all legions' })
8  @ApiResponse({ status: 200, description: 'List of Empire legions' })
9  @Get()
10  findAll() {
11    return [
12      { name: 'Legio X Gemina', location: 'Pannonia' },
13      { name: 'Legio III Augusta', location: 'Africa' },
14    ];
15  }
16}

Chaque décorateur @Api... est comme un sceau officiel sur un document - il lui confère un caractère officiel et décrit l'objectif de l'endpoint.

Décorateurs Swagger de base

Exercice pratique

Regarde le code ci-dessous, qui montre la configuration Swagger de base dans un projet NestJS :

1// Imperium Chronicles - Introduction à Swagger
2import { Controller, Get } from '@nestjs/common';
3import { ApiTags, ApiOperation, ApiResponse } from '@nestjs/swagger';
4
5// Les décorateurs Swagger décrivent les endpoints comme des chroniques impériales
6// Chaque décorateur ajoute des informations à la documentation de l'API
7
8@ApiTags('Imperium')
9@Controller()
10export class AppController {
11  @ApiOperation({ summary: 'Status Imperium' })
12  @ApiResponse({ status: 200, description: 'Imperium working correctly' })
13  @Get()
14  getStatus() {
15    return {
16      imperium: 'Roma Aeterna',
17      status: 'Active',
18      annales: 'Swagger UI disponible sur /api/docs',
19    };
20  }
21
22  @ApiOperation({ summary: "Informations sur l'API" })
23  @ApiResponse({ status: 200, description: 'Imperium API metadata' })
24  @Get('info')
25  getInfo() {
26    return {
27      name: 'Imperium Romanum API',
28      version: '1.0',
29      description: 'API de gestion des légions et des provinces',
30      documentation: '/api/docs',
31    };
32  }
33}
34
35// OpenAPI / Swagger est un standard pour décrire les API REST
36// @nestjs/swagger génère la documentation automatiquement
37// Swagger UI permet de parcourir et de tester les endpoints
38
39console.log("Swagger = Imperium Chronicles");
40console.log("OpenAPI = Standard de description d'API");
41console.log("@ApiTags = Livres des annales (regroupement)");
42console.log("@ApiOperation = Décret impérial (description de l'endpoint)");
43console.log("@ApiResponse = Édit de réponse (réponses possibles)");
44