API Swagger Documentée
Environnement
Node.js, Express, Docker, MS SQL Server
Technologies
JavaScript, Swagger UI Express, mssql, Postman
Base de données
MS SQL Server, Requêtes SQL, Connexion sécurisée
Avantages obtenus
- Documentation interactive et claire des endpoints de l'API
- Simplification de l'utilisation de l'API pour les développeurs
- Tests facilités grâce à l'interface Swagger
- Maintenance simplifiée de l'API et de sa documentation
Présentation du projet
Dans ce projet, j'ai conçu une API REST permettant de récupérer des informations à partir d'une base de données MS SQL Server dockerisée. L'objectif principal était de créer une interface programmatique robuste et bien documentée pour faciliter l'accès aux données pour les développeurs.
La documentation a été réalisée avec Swagger pour décrire chaque endpoint de manière claire et précise. Cette approche permet non seulement de documenter l'API, mais aussi de la tester directement via l'interface utilisateur générée par Swagger, ce qui simplifie considérablement le développement et l'intégration.
Défis techniques
Intégration avec MS SQL Server
Établir une connexion fiable et sécurisée entre l'API Node.js et la base de données MS SQL Server dockerisée, tout en gérant efficacement les requêtes et les transactions.
Solution mise en œuvre
J'ai utilisé le package mssql pour Node.js, qui offre une interface robuste pour interagir avec MS SQL Server. J'ai mis en place un pool de connexions pour optimiser les performances et configuré des paramètres de sécurité appropriés. J'ai également créé des fonctions d'abstraction pour simplifier l'exécution des requêtes SQL et la gestion des erreurs.
// Configuration du pool de connexions SQL
const pool = new sql.ConnectionPool({
user: process.env.DB_USER,
password: process.env.DB_PASSWORD,
server: process.env.DB_SERVER,
database: process.env.DB_NAME,
options: {
encrypt: true,
trustServerCertificate: true
}
});
// Fonction d'abstraction pour exécuter des requêtes
async function executeQuery(query, params = []) {
try {
const poolConnection = await pool.connect();
const result = await poolConnection.request()
.input('param1', sql.VarChar, params[0])
.query(query);
poolConnection.release();
return result.recordset;
} catch (err) {
console.error('SQL error', err);
throw new Error('Database query failed');
}
}Documentation Swagger complète
Créer une documentation Swagger complète et précise pour tous les endpoints de l'API, avec des exemples de requêtes et de réponses pour chaque cas d'utilisation.
Solution mise en œuvre
J'ai utilisé swagger-jsdoc pour générer la documentation à partir de commentaires JSDoc dans le code, et swagger-ui-express pour créer l'interface utilisateur interactive. J'ai documenté chaque endpoint avec des descriptions détaillées, des paramètres, des exemples de requêtes et de réponses, ainsi que des codes d'erreur possibles.
/**
* @swagger
* /api/users:
* get:
* summary: Récupère la liste des utilisateurs
* description: Retourne une liste paginée de tous les utilisateurs
* parameters:
* - in: query
* name: page
* schema:
* type: integer
* description: Numéro de page pour la pagination
* - in: query
* name: limit
* schema:
* type: integer
* description: Nombre d'éléments par page
* responses:
* 200:
* description: Liste des utilisateurs récupérée avec succès
* content:
* application/json:
* schema:
* type: object
* properties:
* users:
* type: array
* items:
* $ref: '#/components/schemas/User'
* total:
* type: integer
* 500:
* description: Erreur serveur
*/
router.get('/users', async (req, res) => {
// Implémentation de la route
});Déploiement dans un conteneur Docker
Configurer l'API pour qu'elle fonctionne correctement dans un environnement Docker, en s'assurant qu'elle puisse communiquer avec la base de données MS SQL Server également conteneurisée.
Solution mise en œuvre
J'ai créé un Dockerfile optimisé pour l'API Node.js, en utilisant une image de base légère (node:14-alpine) et en configurant les variables d'environnement nécessaires. J'ai également mis en place un fichier docker-compose.yml pour orchestrer l'API et la base de données, en définissant les réseaux appropriés pour permettre la communication entre les conteneurs.
Étapes principales du projet
Configuration de l'API
J'ai commencé par mettre en place l'architecture de base de l'API avec Node.js et Express. J'ai créé les routes et les contrôleurs nécessaires pour gérer les différentes fonctionnalités, en suivant les principes REST. J'ai également configuré la connexion à la base de données MS SQL Server à l'aide du package mssql.
// Structure du projet
├── src/
│ ├── controllers/
│ │ ├── userController.js
│ │ ├── productController.js
│ │ └── orderController.js
│ ├── routes/
│ │ ├── userRoutes.js
│ │ ├── productRoutes.js
│ │ └── orderRoutes.js
│ ├── models/
│ │ ├── userModel.js
│ │ ├── productModel.js
│ │ └── orderModel.js
│ ├── config/
│ │ ├── database.js
│ │ └── swagger.js
│ ├── middleware/
│ │ ├── auth.js
│ │ └── errorHandler.js
│ └── app.js
├── package.json
└── DockerfileImplémentation des endpoints
J'ai développé les différents endpoints de l'API pour permettre la récupération, la création, la modification et la suppression des données. J'ai mis en place une validation des entrées pour garantir l'intégrité des données et une gestion appropriée des erreurs pour améliorer l'expérience des développeurs.
// Exemple d'un contrôleur pour les utilisateurs
const getUserById = async (req, res) => {
try {
const { id } = req.params;
// Validation de l'ID
if (!id || isNaN(parseInt(id))) {
return res.status(400).json({
error: 'ID utilisateur invalide'
});
}
// Récupération de l'utilisateur depuis la base de données
const user = await userModel.findById(id);
if (!user) {
return res.status(404).json({
error: 'Utilisateur non trouvé'
});
}
return res.status(200).json(user);
} catch (error) {
console.error('Erreur lors de la récupération de l'utilisateur:', error);
return res.status(500).json({
error: 'Erreur serveur lors de la récupération de l'utilisateur'
});
}
};Documentation avec Swagger
J'ai intégré Swagger à l'API en utilisant swagger-jsdoc et swagger-ui-express. J'ai documenté chaque endpoint avec des commentaires JSDoc détaillés, incluant des descriptions, des paramètres, des exemples de requêtes et de réponses, ainsi que des codes d'erreur possibles.
// Configuration de Swagger
const swaggerOptions = {
definition: {
openapi: '3.0.0',
info: {
title: 'API Documentation',
version: '1.0.0',
description: 'Documentation de l'API REST',
contact: {
name: 'Lilyan Giraud',
email: 'contact@example.com'
}
},
servers: [
{
url: 'http://localhost:3000',
description: 'Serveur de développement'
}
]
},
apis: ['./src/routes/*.js']
};
const swaggerSpec = swaggerJsDoc(swaggerOptions);
app.use('/api-docs', swaggerUi.serve, swaggerUi.setup(swaggerSpec));Conteneurisation avec Docker
J'ai créé un Dockerfile pour l'API et configuré un fichier docker-compose.yml pour orchestrer l'API et la base de données MS SQL Server. J'ai défini les réseaux appropriés pour permettre la communication entre les conteneurs et configuré les variables d'environnement nécessaires.
Tests et validation
J'ai testé l'API en utilisant Postman pour vérifier le bon fonctionnement de chaque endpoint. J'ai également utilisé l'interface Swagger générée pour tester l'API directement depuis la documentation. J'ai validé que toutes les fonctionnalités répondaient aux exigences et que la documentation était claire et précise.
Avantages de Swagger pour la documentation d'API
Documentation interactive
Swagger génère une interface utilisateur interactive qui permet aux développeurs de comprendre facilement l'API et de tester directement les endpoints sans outils supplémentaires.
Génération de code client
À partir de la spécification Swagger, il est possible de générer automatiquement du code client dans différents langages, ce qui facilite l'intégration de l'API dans diverses applications.
Standardisation
Swagger utilise la spécification OpenAPI, un standard de l'industrie pour la documentation des API REST, ce qui garantit une documentation cohérente et compréhensible par tous.
Maintenance simplifiée
La documentation est générée à partir de commentaires dans le code, ce qui facilite sa maintenance et garantit qu'elle reste synchronisée avec l'implémentation de l'API.
Compétences acquises
Développement d'API REST
Conception et implémentation d'API RESTful suivant les bonnes pratiques et les standards de l'industrie
Documentation avec Swagger
Utilisation de swagger-jsdoc et swagger-ui-express pour créer une documentation interactive et complète
Intégration de bases de données
Configuration et utilisation de MS SQL Server avec Node.js, gestion des connexions et des requêtes
Conteneurisation avec Docker
Création de conteneurs Docker pour des applications Node.js et des bases de données, orchestration avec docker-compose
Conclusion
La création d'une API REST documentée avec Swagger a permis de mettre en place une interface programmatique robuste et facile à utiliser pour accéder aux données stockées dans une base de données MS SQL Server. La documentation interactive générée par Swagger facilite grandement la compréhension et l'utilisation de l'API par les développeurs.
Ce projet m'a permis d'approfondir mes compétences en développement backend, en gestion de bases de données et en documentation d'API. J'ai également acquis une expérience précieuse dans la conteneurisation d'applications avec Docker, ce qui est essentiel pour le déploiement moderne d'applications. Les connaissances et compétences acquises lors de ce projet sont directement applicables à d'autres projets de développement d'API et contribuent à ma croissance en tant que développeur.