Tutoriel pratique Swagger : API de gestion de livres
Ce tutoriel vous guidera dans la mise en œuvre d'une API de système de gestion de livres basée sur Swagger. Les principales fonctionnalités incluent :
- Opérations CRUD pour les livres
- Requêtes paginées
- Filtrage basé sur des conditions
- Génération automatique de documentation d'API
- Tests d'API en ligne
Stack technique :
- Node.js + Express
- Swagger UI Express
- Swagger JSDoc
Préparation de l’environnement
Installer Node.js
Assurez-vous que Node.js est installé sur votre système (v14.0.0 ou version ultérieure recommandée).
Vérification de l'environnement
node -v npm -v
Initialisation du projet
Créer le répertoire du projet
mkdir book-management-api cd book-management-api npm init -y
Installer les dépendances
npm install express cors swagger-ui-express swagger-jsdoc nodemon --save
Créer la structure de base du projet
book-management-api/ ├── node_modules/ ├── models/ │ └── book.js ├── routes/ │ └── books.js ├── middleware/ │ └── auth.js ├── swagger/ │ └── swagger.js ├── app.js └── package.json
Créer le fichier d'entrée app.js
Exemple
const cors = require('cors');
const swaggerUi = require('swagger-ui-express');
const swaggerSpec = require('./swagger/swagger');
const booksRouter = require('./routes/books');
const app = express();
const PORT = process.env.PORT || 3000;
// Intergiciel
app.use(cors());
app.use(express.json());
app.use(express.urlencoded({ extended: true }));
// Routes de l'API
app.use('/api/books', booksRouter);
// Documentation Swagger
app.use('/api-docs', swaggerUi.serve, swaggerUi.setup(swaggerSpec));
// Démarrer le serveur
app.listen(PORT, () => {
console.log(`Service démarré, accédez à http://localhost:${PORT}`);
console.log(`Adresse de la documentation de l'API: http://localhost:${PORT}/api-docs`);
});
Conception et implémentation d'API
Créer le modèle Book
Dansmodels/book.jsCréer un modèle de données simple en mémoire :
Exemple
let books = [
{ id: 1, title: 'Compréhension approfondie de JavaScript', author: 'Douglas Crockford', publishDate: '2008-01-01', isbn: '978-0596517748', category: 'Programmation' },
{ id: 2, title: 'Node.js en action', author: 'Alex Young', publishDate: '2014-08-01', isbn: '978-1617290572', category: 'Programmation' },
{ id: 3, title: 'Le Problème à trois corps', author: 'Liu Cixin', publishDate: '2008-01-01', isbn: '978-7536692387', category: 'Science-fiction' }
];
let nextId = 4;
module.exports = {
// Récupérer tous les livres
getAll: (page = 1, limit = 10, filter = {}) => {
let result = [...books];
// Appliquer les conditions de filtrage
if (filter.category) {
result = result.filter(book => book.category === filter.category);
}
if (filter.author) {
result = result.filter(book => book.author.includes(filter.author));
}
if (filter.title) {
result = result.filter(book => book.title.includes(filter.title));
}
// Calculer la pagination
const startIndex = (page - 1) * limit;
const endIndex = page * limit;
return {
total: result.length,
page: page,
limit: limit,
data: result.slice(startIndex, endIndex)
};
},
// Récupérer un seul livre
getById: (id) => {
return books.find(book => book.id === id);
},
// Créer un livre
create: (book) => {
const newBook = { ...book, id: nextId++ };
books.push(newBook);
return newBook;
},
// Mettre à jour un livre
update: (id, bookData) => {
const index = books.findIndex(book => book.id === id);
if (index !== -1) {
books[index] = { ...books[index], ...bookData };
return books[index];
}
return null;
},
// Supprimer le livre
delete: (id) => {
const index = books.findIndex(book => book.id === id);
if (index !== -1) {
const deletedBook = books[index];
books.splice(index, 1);
return deletedBook;
}
return null;
}
};
Implémenter le contrôleur de route
Dansroutes/books.jsImplémenter les routes API :
Exemple
const express = require('express');
const router = express.Router();
const Book = require('../models/book');
/**
* @swagger
* components:
* schemas:
* Book:
* type: object
* required:
* - title
* - author
* - isbn
* properties:
* id:
* type: integer
* description: ID du livre
* title:
* type: string
* description: Titre du livre
* author:
* type: string
* description: Auteur
* publishDate:
* type: string
* format: date
* description: Date de publication
* isbn:
* type: string
* description: Numéro ISBN
* category:
* type: string
* description: Catégorie de livre
*/
/**
* @swagger
* /api/books:
* get:
* summary: Obtenir la liste des livres
* description: Renvoyer tous les livres, prend en charge la pagination et le filtrage
* parameters:
* - in: query
* name: page
* schema:
* type: integer
* default: 1
* description: Numéro de page
* - in: query
* name: limit
* schema:
* type: integer
* default: 10
* description: Nombre par page
* - in: query
* name: category
* schema:
* type: string
* description: Filtrer par catégorie
* - in: query
* name: author
* schema:
* type: string
* description: Filtrer par auteur
* - in: query
* name: title
* schema:
* type: string
* description: Filtrer par titre
* responses:
* 200:
* description: Liste de livres récupérée avec succès
* content:
* application/json:
* schema:
* type: object
* properties:
* total:
* type: integer
* page:
* type: integer
* limit:
* type: integer
* data:
* type: array
* items:
* $ref: '#/components/schemas/Book'
*/
router.get('/', (req, res) => {
const page = parseInt(req.query.page) || 1;
const limit = parseInt(req.query.limit) || 10;
const filter = {};
if (req.query.category) filter.category = req.query.category;
if (req.query.author) filter.author = req.query.author;
if (req.query.title) filter.title = req.query.title;
const result = Book.getAll(page, limit, filter);
res.json(result);
});
/**
* @swagger
* /api/books/{id}:
* get:
* summary: Obtenir un seul livre
* description: Obtenir des informations détaillées sur un livre spécifique par ID
* parameters:
* - in: path
* name: id
* required: true
* schema:
* type: integer
* description: ID du livre
* responses:
* 200:
* description: Livre récupéré avec succès
* content:
* application/json:
* schema:
* $ref: '#/components/schemas/Book'
* 404:
* description: Livre introuvable
*/
router.get('/:id', (req, res) => {
const id = parseInt(req.params.id);
const book = Book.getById(id);
if (book) {
res.json(book);
} else {
res.status(404).json({ message: 'Book not found' });
}
});
/**
* @swagger
* /api/books:
* post:
* summary: Créer un nouveau livre
* description: Ajouter un nouveau livre au système
* requestBody:
* required: true
* content:
* application/json:
* schema:
* type: object
* required:
* - title
* - author
* - isbn
* properties:
* title:
* type: string
* author:
* type: string
* publishDate:
* type: string
* format: date
* isbn:
* type: string
* category:
* type: string
* responses:
* 201:
* description: Livre créé avec succès
* content:
* application/json:
* schema:
* $ref: '#/components/schemas/Book'
* 400:
* description: Données d'entrée invalides
*/
router.post('/', (req, res) => {
// Validation simple
if (!req.body.title || !req.body.author || !req.body.isbn) {
return res.status(400).json({ message: 'Titre, auteur et ISBN sont des champs obligatoires' });
}
const newBook = Book.create(req.body);
res.status(201).json(newBook);
});
/**
* @swagger
* /api/books/{id}:
* put:
* summary: Mettre à jour un livre
* description: Mettre à jour les informations d'un livre spécifique par ID
* parameters:
* - in: path
* name: id
* required: true
* schema:
* type: integer
* description: ID du livre
* requestBody:
* required: true
* content:
* application/json:
* schema:
* type: object
* properties:
* title:
* type: string
* author:
* type: string
* publishDate:
* type: string
* format: date
* isbn:
* type: string
* category:
* type: string
* responses:
* 200:
* description: Livre mis à jour avec succès
* content:
* application/json:
* schema:
* $ref: '#/components/schemas/Book'
* 404:
* description: Livre introuvable
*/
router.put('/:id', (req, res) => {
const id = parseInt(req.params.id);
const updatedBook = Book.update(id, req.body);
if (updatedBook) {
res.json(updatedBook);
} else {
res.status(404).json({ message: 'Book not found' });
}
});
/**
* @swagger
* /api/books/{id}:
* delete:
* summary: Supprimer un livre
* description: Supprimer un livre spécifique par ID
* parameters:
* - in: path
* name: id
* required: true
* schema:
* type: integer
* description: ID du livre
* responses:
* 200:
* description: Livre supprimé avec succès
* 404:
* description: Livre introuvable
*/
router.delete('/:id', (req, res) => {
const id = parseInt(req.params.id);
const deletedBook = Book.delete(id);
if (deletedBook) {
res.json({ message: 'Livre supprimé avec succès', book: deletedBook });
} else {
res.status(404).json({ message: 'Book not found' });
}
});
module.exports = router;
Configuration de la documentation Swagger
Configurer Swagger
Créezswagger/swagger.jsFichier :
Exemple
const swaggerJsdoc = require('swagger-jsdoc');
const options = {
définition: {
openapi: '3.0.0',
informations: {
title: 'API de gestion de livres',
version: '1.0.0',
description: 'Une API d'un système de gestion de livres construite avec Express et Swagger',
contact: {
name: 'Développeur',
email: 'dev@example.com'
}
},
servers: [
{
url: 'http://localhost:3000',
description: 'Serveur de développement'
}
]
},
// Analyser tous les fichiers JS contenant des annotations
apis: ['./routes/*.js']
};
const swaggerSpec = swaggerJsdoc(options);
module.exports = swaggerSpec;
Ajouter un middleware d'authentification
Créezmiddleware/auth.js:
Exemple
const jwt = require('jsonwebtoken');
// Middleware d'authentification JWT simple
const authMiddleware = (req, res, next) => {
const token = req.header('Authorization')?.replace('Bearer ', '');
if (!token) {
return res.status(401).json({ message: 'Aucun jeton d'authentification fourni' });
}
try {
// Dans une application réelle, vous devez vérifier le token JWT ici
// const decoded = jwt.verify(token, process.env.JWT_SECRET);
// req.user = decoded.user;
// Pour simplifier le tutoriel, nous ignorons la vérification
req.user = { id: 1, role: 'admin' };
next();
} catch (error) {
return res.status(401).json({ message: 'Jeton d'authentification invalide' });
}
};
module.exports = authMiddleware;
Test fonctionnel d'API
Démarrer le serveur
Utilisez la commande suivante pour démarrer le serveur :
# 如果已配置了package.json中的scripts,执行: npm start # 或者直接使用nodemon npx nodemon app.js
6.2 Accéder à la documentation Swagger
Ouvrez un navigateur et visitez : http://localhost:3000/api-docs
Utiliser Swagger pour tester les API
-
Récupérer tous les livres
- Cliquez sur le point de terminaison GET /api/books
- Cliquez sur le bouton « Try it out »
- Vous pouvez définir les paramètres de pagination page et limit, ainsi que les conditions de filtrage
- Cliquez sur le bouton « Execute » pour envoyer la requête
- Observez les résultats
-
Créer un nouveau livre
- Cliquez sur l'endpoint POST /api/books
- Cliquez sur le bouton « Try it out »
Remplissez les informations du livre dans le corps de la requête, par exemple :
{ "title": "RESTful API设计", "author": "Martin Fowler", "publishDate": "2020-01-01", "isbn": "978-1234567890", "category": "编程" }- Cliquez sur le bouton « Execute » pour envoyer la requête
- Observez les résultats
-
Récupérer, mettre à jour et supprimer
- Testez les autres endpoints en utilisant des méthodes similaires
Dépannage des problèmes courants
Problème de cross-origin
Si l'application frontend et l'API ne s'exécutent pas sur le même domaine, vous pouvez rencontrer des problèmes de cross-origin. Nous avons déjà configuré le middleware CORS au point d'entrée de l'application :
app.use(cors());
Si un contrôle plus fin est nécessaire, vous pouvez le configurer comme ceci :
Exemple
origin: ['http://localhost:8080', 'https://your-frontend-domain.com'],
methods: ['GET', 'POST', 'PUT', 'DELETE'],
allowedHeaders: ['Content-Type', 'Authorization'],
credentials: true
};
app.use(cors(corsOptions));
Erreur de configuration d'authentification
Les problèmes d'authentification apparaissent généralement dans les domaines suivants :
-
Erreur de configuration JWT
Assurez-vous
JWT_SECRETLes variables d'environnement sont correctement définies :// 在应用启动时检查 if (!process.env.JWT_SECRET) { console.warn('警告: JWT_SECRET环境变量未设置,认证可能不安全'); } -
Middleware d'authentification utilisé incorrectement
Assurez-vous que le middleware est correctement appliqué aux routes qui nécessitent une authentification :
const auth = require('../middleware/auth'); // 公开路由 - 无需认证 router.get('/', (req, res) => { /* ... */ }); // 受保护路由 - 需要认证 router.post('/', auth, (req, res) => { /* ... */ }); router.put('/:id', auth, (req, res) => { /* ... */ }); router.delete('/:id', auth, (req, res) => { /* ... */ }); -
Configuration de l'authentification dans la documentation Swagger
Mettez à jour la configuration Swagger pour prendre en charge l'authentification Bearer Token :
// swagger/swagger.js const options = { definition: { // ... 其他配置 ... components: { securitySchemes: { bearerAuth: { type: 'http', scheme: 'bearer', bearerFormat: 'JWT' } } }, security: [ { bearerAuth: [] } ] }, // ... 其他配置 ... }; -
Configuration de l'en-tête de requête
Assurez-vous que le client définit correctement l'en-tête d'authentification lors de l'envoi de requêtes :
// 前端示例代码 - 使用fetch API const token = localStorage.getItem('token'); fetch('http://localhost:3000/api/books', { method: 'POST', headers: { 'Content-Type': 'application/json', 'Authorization': `Bearer ${token}` }, body: JSON.stringify(bookData) }) .then(response => response.json()) .then(data => console.log(data)) .catch(error => console.error('错误:', error));
La documentation Swagger ne se met pas à jour
Si vous mettez à jour les commentaires JSDoc mais que la documentation Swagger ne se met pas à jour, essayez les solutions suivantes :
-
Assurez-vous que la configuration du chemin est correcte
// swagger/swagger.js const options = { // ... 其他配置 ... apis: ['./routes/*.js', './models/*.js'] // 确保包含所有需要生成文档的文件 }; -
Redémarrez le serveur
Parfois, vous devez redémarrer le serveur pour voir la nouvelle documentation Swagger.
-
Videz le cache du navigateur
Utilisez Ctrl+F5 pour forcer l'actualisation de la page.
Fonctionnalités avancées
Ajouter la gestion des versions de l'API
Modifiez le fichier d'entrée de l'application :
// app.js
// ... 其他导入 ...
// API v1
app.use('/api/v1/books', booksRouter);
// 为未来的API v2预留
// app.use('/api/v2/books', booksRouterV2);
// ... 其他代码 ...
Ajouter la validation des requêtes
Utilisez un middleware de validation Express (tel queexpress-validator):
npm install express-validator --save
Ensuite, utilisez-le dans la route :
Exemple
const { body, validationResult } = require('express-validator');
// Règles de validation pour la création d'un livre
const validateBook = [
body('title').notEmpty().withMessage('Le titre ne peut pas être vide'),
body('author').notEmpty().withMessage('L’auteur ne peut pas être vide'),
body('isbn').notEmpty().withMessage('L’ISBN ne peut pas être vide')
.matches(/^(?=(?:\D*\d){10}(?:(?:\D*\d){3})?$)[\d-]+$/).withMessage('Format d’ISBN invalide'),
body('publishDate').optional().isDate().withMessage('Format de date de publication invalide'),
// Middleware de gestion du résultat de validation
(req, res, next) => {
const errors = validationResult(req);
if (!errors.isEmpty()) {
return res.status(400).json({ errors: errors.array() });
}
next();
}
];
// Utiliser la validation dans les routes
router.post('/', validateBook, (req, res) => {
// ... Code pour créer un livre ...
});
Ajouter la compression des réponses
Utilisez un middleware de compression pour réduire la taille de la réponse :
npm install compression --save
Ajoutez-le ensuite au fichier d'entrée de l'application :
// app.js
const compression = require('compression');
// ... 其他代码 ...
// 启用压缩
app.use(compression());
// ... 其他代码 ...
Ajouter la mise en cache des réponses
Pour améliorer les performances, vous pouvez ajouter la mise en cache des réponses :
npm install apicache --save
Utilisez-le ensuite au point d'entrée de l'application :
// app.js
const apicache = require('apicache');
const cache = apicache.middleware;
// ... 其他代码 ...
// 缓存GET请求5分钟
app.use('/api', cache('5 minutes'));
// ... 其他代码 ...
Ajouter la limitation du débit des requêtes
Prévenez les abus d'API :
npm install express-rate-limit --save
Utilisez-le ensuite au point d'entrée de l'application :
// app.js
const rateLimit = require('express-rate-limit');
// ... 其他代码 ...
// 创建限流中间件
const apiLimiter = rateLimit({
windowMs: 15 * 60 * 1000, // 15分钟
max: 100, // 每个IP在windowMs时间内最多100个请求
message: '来自此IP的请求过多,请稍后再试'
});
// 应用限流中间件
app.use('/api', apiLimiter);
// ... 其他代码 ... Autres extensions