Documenter son API
Swagger et OpenAPI
Pourquoi documenter une API ?
- Faciliter la compréhension : Les développeurs savent exactement comment interagir avec l'API (endpoints, paramètres, types de données).
- Réduire les erreurs : Les spécifications claires minimisent le risque d'erreurs lors de l'intégration de l'API.
- Améliorer la maintenabilité : En documentant bien l'API, vous facilitez son évolution et son extension.
Qu'est-ce que Swagger/OpenAPI ?
Swagger est un ensemble d'outils et de spécifications qui permettent de documenter et de tester des API. OpenAPI est la spécification de base utilisée par Swagger.
Les principaux composants de Swagger/OpenAPI :
- Spécification OpenAPI : Un format de fichier (généralement en YAML ou JSON) qui décrit toutes les routes, paramètres, réponses et autres aspects d'une API.
- Swagger UI : Une interface utilisateur qui permet de visualiser la documentation de l'API et d'interagir avec elle via un navigateur.
Intégrer Swagger dans une API Node.js avec Express
Installation des dépendances nécessaires
Pour intégrer Swagger dans une application Node.js avec Express, vous aurez besoin de quelques dépendances supplémentaires :
npm install swagger-ui-express yamljs
npm install -D @types/swagger-ui-express @types/yamljs
swagger-ui-express: Le middleware pour intégrer Swagger UI dans votre application.yamljs: Pour charger et analyser les fichiers YAML (où sera écrite la spécification OpenAPI).
Créer le fichier de spécification OpenAPI
Créez un fichier swagger.yaml dans votre projet. Ce fichier contiendra la description de votre API.
Voici un exemple simple de fichier swagger.yaml :
openapi: 3.0.0
info:
title: Prisma User API
version: 1.0.0
description: API pour gérer les utilisateurs et leurs posts
servers:
- url: http://localhost:3000
description: Serveur local
paths:
/users:
get:
summary: Récupère tous les utilisateurs
responses:
'200':
description: Liste des utilisateurs avec leurs posts
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/UserWithPosts'
'204':
description: Aucun utilisateur trouvé
post:
summary: Crée un nouvel utilisateur
security:
- bearerAuth: []
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
name:
type: string
example: John Doe
responses:
'201':
description: Utilisateur créé
content:
application/json:
schema:
$ref: '#/components/schemas/User'
'401':
description: Non autorisé (token manquant ou invalide)
content:
application/json:
schema:
type: object
properties:
error:
type: string
example: Unauthorized
/users/{userId}:
get:
summary: Récupère un utilisateur par son ID
parameters:
- name: userId
in: path
required: true
schema:
type: integer
description: ID de l'utilisateur
responses:
'200':
description: Utilisateur trouvé avec ses posts
content:
application/json:
schema:
$ref: '#/components/schemas/UserWithPosts'
'404':
description: Utilisateur non trouvé
content:
text/plain:
schema:
type: string
example: Utilisateur non trouvé
components:
securitySchemes:
bearerAuth:
type: http
scheme: bearer
bearerFormat: JWT
schemas:
User:
type: object
properties:
id:
type: integer
example: 1
name:
type: string
example: John Doe
Post:
type: object
properties:
id:
type: integer
example: 1
title:
type: string
example: My First Post
authorId:
type: integer
example: 1
UserWithPosts:
allOf:
- $ref: '#/components/schemas/User'
- type: object
properties:
posts:
type: array
items:
$ref: '#/components/schemas/Post'
C'est dans ce genre de travail d'automatisation qu'une IA peut être utile. En effet, elle pourrait générer automatiquement ce genre de fichier à partir du code source de l'API.
Configurer Swagger dans votre application Express
Dans votre fichier principal index.ts, vous devez intégrer Swagger UI pour afficher la documentation.
import express from 'express';
import swaggerUi from 'swagger-ui-express';
import YAML from 'yamljs';
import path from 'path';
export const app = express();
const port = 3000;
// Charger la spécification Swagger
const swaggerDocument = YAML.load(path.join(__dirname, './swagger.yaml'));
// Serveur Swagger UI à l'adresse /api-docs
app.use('/api-docs', swaggerUi.serve, swaggerUi.setup(swaggerDocument));
// Exemple d'API
app.get('/users', (req, res) => {
res.status(201).json([
{ id: 1, name: 'Alice' },
{ id: 2, name: 'Bob' },
]);
});
app.post('/users', (req, res) => {
const { name } = req.body;
res.status(201).json({ id: 3, name });
});
app.listen(port, () => {
console.log(`Mon serveur démarre sur le port ${port}`);
});
Tester l'API et la documentation
Une fois votre application lancée, vous pouvez accéder à la documentation Swagger UI en naviguant à l'adresse http://localhost:3000/api-docs dans votre navigateur. Vous y trouverez toutes les informations sur vos endpoints, et vous pourrez tester les différentes requêtes API directement à partir de l'interface Swagger.