L'une des parties les plus cruciales du développement d'une API est sa documentation. Une API bien documentée est un outil puissant pour les développeurs car elle la rend facile à utiliser et à comprendre. Dans ce chapitre, nous verrons comment documenter une API créée avec NodeJS et MongoDB, en nous concentrant sur un CRUD (Créer, Lire, Mettre à jour, Supprimer).
Nous allons commencer par créer une nouvelle route dans notre application NodeJS. Nous utiliserons Express, un framework populaire pour NodeJS, pour créer nos routes. Notre itinéraire sera responsable de la gestion de toutes les opérations CRUD pour une ressource spécifique. Nous utiliserons MongoDB, une base de données NoSQL, pour stocker nos données.
Tout d'abord, définissons notre itinéraire. Dans notre fichier de routes, nous ajoutons le code suivant :
const express = require('express');
const routeur = express.Router();
const ResourceController = require('../controllers/resourceController');
router.get('/', ResourceController.getAll);
router.post('/', ResourceController.create);
router.get('/:id', ResourceController.getOne);
router.put('/:id', ResourceController.update);
router.delete('/:id', ResourceController.delete);
module.exports = routeur ;
Ce code définit une nouvelle route qui gère toutes les opérations CRUD pour une ressource. Le ResourceController est un contrôleur que nous allons créer prochainement et qui gérera la logique de chaque opération.
Créons maintenant notre contrôleur. Dans un nouveau fichier, ajoutez le code suivant :
const Resource = require('../models/resource');
exports.getAll = async (req, res) => {
const resources = attendre Resource.find();
res.json(ressources);
} ;
exports.create = async (req, res) => {
const newResource = nouvelle ressource (req.body);
const ressource = attendre newResource.save();
res.json(ressource);
} ;
exports.getOne = async (req, res) => {
const ressource = attendre Resource.findById(req.params.id);
res.json(ressource);
} ;
exports.update = async (req, res) => {
const resource = wait Resource.findByIdAndUpdate(req.params.id, req.body, {new : true});
res.json(ressource);
} ;
exports.delete = async (req, res) => {
attendre Resource.findByIdAndRemove(req.params.id);
res.json({message : 'Ressource supprimée'});
} ;
Ce code définit un contrôleur qui gère toutes les opérations CRUD pour une ressource. Il utilise le modèle Resource que nous allons créer prochainement pour interagir avec notre base de données MongoDB.
Maintenant, créons notre modèle. Dans un nouveau fichier, ajoutez le code suivant :
const mangouste = require('mangouste');
const ResourceSchema = nouvelle mangouste.Schema ({
nom: {
tapez : chaîne,
obligatoire : vrai
},
description: {
tapez : chaîne,
obligatoire : vrai
}
});
module.exports = mangouste.model('Resource', ResourceSchema);
Ce code définit un modèle pour nos ressources. Il utilise Mongoose, une bibliothèque populaire pour MongoDB, pour définir un schéma pour nos données.
Maintenant que notre API est configurée, il est temps de la documenter. La documentation est cruciale pour garantir que les autres développeurs peuvent comprendre et utiliser correctement notre API. Il existe plusieurs outils disponibles pour documenter les API, mais l'un des plus populaires est Swagger.
Swagger est un outil de documentation d'API qui permet aux développeurs de définir la structure de leur API à l'aide d'un format de description d'API. Il génère une interface utilisateur interactive qui permet aux développeurs d'explorer et de tester l'API.
Pour utiliser Swagger, nous devons d'abord installer le package swagger-ui-express :
npm installer swagger-ui-express
Ensuite, nous pouvons ajouter le code suivant à notre fichier de routes :
const swaggerUi = require('swagger-ui-express');
const swaggerDocument = require('./swagger.json');
router.use('/api-docs', swaggerUi.serve);
router.get('/api-docs', swaggerUi.setup(swaggerDocument));
Ce code sert notre documentation Swagger dans /api-docs. Le fichier swagger.json est l'endroit où nous définirons la structure de notre API.
Dans notre fichier swagger.json, nous pouvons ajouter le code suivant :
{
"openapi": "3.0.0",
"Info": {
"title": "API de ressources",
"version": "1.0.0",
"description": "API de gestion des ressources"
},
"chemins": {
"/": {
"obtenir": {
"summary": "Obtenir toutes les ressources",
"réponses": {
"200" : {
"description": "Une liste de ressources"
}
}
},
"poste": {
"summary": "Créer une nouvelle ressource",
"réponses": {
"200" : {
"description": "La ressource créée"
}
}
}
},
"/{identifiant}": {
"obtenir":{
"summary": "Obtenir une ressource spécifique",
"réponses": {
"200" : {
"description": "La ressource demandée"
}
}
},
"mettre": {
"summary": "Mettre à jour une ressource spécifique",
"réponses": {
"200" : {
"description": "La ressource mise à jour"
}
}
},
"supprimer": {
"summary": "Supprimer une ressource spécifique",
"réponses": {
"200" : {
"description": "Confirmation de suppression"
}
}
}
}
}
}
Ce code définit la structure de notre API, y compris toutes les opérations CRUD que nous implémentons. Il fournit une description et un résumé de chaque opération, ainsi que des codes de réponse possibles.
Avec cela, nous disposons d'une API CRUD complète avec NodeJS et MongoDB, ainsi que sa documentation. Cela permettra aux autres développeurs d'utiliser beaucoup plus facilement notre API.
