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 express = require('express');
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

// models/book.js
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

// routes/books.js
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

// swagger/swagger.js
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

// middleware/auth.js
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

  1. 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
  2. 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
  3. 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

const corsOptions = {
  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 :

  1. Erreur de configuration JWT

    Assurez-vousJWT_SECRETLes variables d'environnement sont correctement définies :

    // 在应用启动时检查
    if (!process.env.JWT_SECRET) {
      console.warn('警告: JWT_SECRET环境变量未设置,认证可能不安全');
    }        
    
  2. 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) => { /* ... */ });
    
  3. 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: []
          }
        ]
      },
      // ... 其他配置 ...
    };
    
  4. 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 :

  1. Assurez-vous que la configuration du chemin est correcte

    // swagger/swagger.js
    const options = {
      // ... 其他配置 ...
      apis: ['./routes/*.js', './models/*.js'] // 确保包含所有需要生成文档的文件
    };
    
  2. Redémarrez le serveur

    Parfois, vous devez redémarrer le serveur pour voir la nouvelle documentation Swagger.

  3. 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

// routes/books.js
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