feat(api): Améliorer la documentation Swagger pour les routes de l'API, ajout de descriptions détaillées et de schémas pour les entités Project, Measurement, Video, Camera, et Error.

2025-04-27 01:20:27 +02:00
parent 1890051a0f
commit 65fa693986
6 changed files with 485 additions and 87 deletions
--- a/src/routes/projectRoutes.js
+++ b/src/routes/projectRoutes.js
@@ -7,12 +7,21 @@ const ProjectController = require('../controllers/projectController');
 * @swagger
 * /projects:
 *   get:
+ *     tags:
+ *       - Projets
 *     summary: Récupère tous les projets
+ *     description: Retourne la liste complète des projets de timelapse
 *     responses:
 *       200:
 *         description: Liste de tous les projets
+ *         content:
+ *           application/json:
+ *             schema:
+ *               type: array
+ *               items:
+ *                 $ref: '#/components/schemas/Project'
 *       500:
- *         description: Erreur serveur
+ *         $ref: '#/components/responses/ServerError'
 */
 router.get('/projects', ProjectController.getAllProjects);

@@ -20,7 +29,10 @@ router.get('/projects', ProjectController.getAllProjects);
 * @swagger
 * /projects/{id}:
 *   get:
+ *     tags:
+ *       - Projets
 *     summary: Récupère un projet par ID
+ *     description: Retourne les détails d'un projet spécifique
 *     parameters:
 *       - in: path
 *         name: id
@@ -31,12 +43,16 @@ router.get('/projects', ProjectController.getAllProjects);
 *     responses:
 *       200:
 *         description: Détails du projet
+ *         content:
+ *           application/json:
+ *             schema:
+ *               $ref: '#/components/schemas/Project'
 *       400:
- *         description: ID de projet invalide
+ *         $ref: '#/components/responses/BadRequest'
 *       404:
- *         description: Projet non trouvé
+ *         $ref: '#/components/responses/NotFound'
 *       500:
- *         description: Erreur serveur
+ *         $ref: '#/components/responses/ServerError'
 */
 router.get('/projects/:id', ProjectController.getProjectById);

@@ -44,7 +60,11 @@ router.get('/projects/:id', ProjectController.getProjectById);
 * @swagger
 * /projects/{id}/videos:
 *   get:
+ *     tags:
+ *       - Projets
+ *       - Vidéos
 *     summary: Récupère les vidéos d'un projet
+ *     description: Retourne toutes les vidéos associées à un projet spécifique
 *     parameters:
 *       - in: path
 *         name: id
@@ -55,12 +75,18 @@ router.get('/projects/:id', ProjectController.getProjectById);
 *     responses:
 *       200:
 *         description: Liste des vidéos du projet
+ *         content:
+ *           application/json:
+ *             schema:
+ *               type: array
+ *               items:
+ *                 $ref: '#/components/schemas/Video'
 *       400:
- *         description: ID de projet invalide
+ *         $ref: '#/components/responses/BadRequest'
 *       404:
- *         description: Aucune vidéo trouvée
+ *         $ref: '#/components/responses/NotFound'
 *       500:
- *         description: Erreur serveur
+ *         $ref: '#/components/responses/ServerError'
 */
 router.get('/projects/:id/videos', ProjectController.getProjectVideos);

@@ -68,7 +94,11 @@ router.get('/projects/:id/videos', ProjectController.getProjectVideos);
 * @swagger
 * /projects/{id}/measurements:
 *   get:
+ *     tags:
+ *       - Projets
+ *       - Mesures
 *     summary: Récupère les mesures d'un projet
+ *     description: Retourne toutes les mesures associées à un projet spécifique
 *     parameters:
 *       - in: path
 *         name: id
@@ -79,12 +109,18 @@ router.get('/projects/:id/videos', ProjectController.getProjectVideos);
 *     responses:
 *       200:
 *         description: Liste des mesures du projet
+ *         content:
+ *           application/json:
+ *             schema:
+ *               type: array
+ *               items:
+ *                 $ref: '#/components/schemas/Measurement'
 *       400:
- *         description: ID de projet invalide
+ *         $ref: '#/components/responses/BadRequest'
 *       404:
- *         description: Aucune mesure trouvée
+ *         $ref: '#/components/responses/NotFound'
 *       500:
- *         description: Erreur serveur
+ *         $ref: '#/components/responses/ServerError'
 */
 router.get('/projects/:id/measurements', ProjectController.getProjectMeasurements);

@@ -92,7 +128,10 @@ router.get('/projects/:id/measurements', ProjectController.getProjectMeasurement
 * @swagger
 * /projects:
 *   post:
+ *     tags:
+ *       - Projets
 *     summary: Crée un nouveau projet
+ *     description: Crée un nouveau projet de timelapse et son répertoire de stockage
 *     requestBody:
 *       required: true
 *       content:
@@ -102,18 +141,31 @@ router.get('/projects/:id/measurements', ProjectController.getProjectMeasurement
 *             properties:
 *               name:
 *                 type: string
+ *                 description: Nom du projet
 *               description:
 *                 type: string
+ *                 description: Description détaillée du projet
 *             required:
 *               - name
 *               - description
 *     responses:
 *       201:
 *         description: Projet créé avec succès
+ *         content:
+ *           application/json:
+ *             schema:
+ *               type: object
+ *               properties:
+ *                 message:
+ *                   type: string
+ *                   example: Projet ajouté avec succès
+ *                 id:
+ *                   type: integer
+ *                   example: 42
 *       400:
- *         description: Paramètres invalides
+ *         $ref: '#/components/responses/BadRequest'
 *       500:
- *         description: Erreur serveur
+ *         $ref: '#/components/responses/ServerError'
 */
 router.post('/projects', ProjectController.createProject);

@@ -121,21 +173,35 @@ router.post('/projects', ProjectController.createProject);
 * @swagger
 * /projects/{id}:
 *   delete:
+ *     tags:
+ *       - Projets
 *     summary: Supprime un projet
+ *     description: Supprime un projet, toutes ses mesures, images et vidéos associées
 *     parameters:
 *       - in: path
 *         name: id
 *         required: true
 *         schema:
 *           type: integer
- *         description: ID du projet
+ *         description: ID du projet à supprimer
 *     responses:
 *       200:
 *         description: Projet supprimé avec succès
+ *         content:
+ *           application/json:
+ *             schema:
+ *               type: object
+ *               properties:
+ *                 message:
+ *                   type: string
+ *                   example: Projet supprimé avec succès
+ *                 id:
+ *                   type: integer
+ *                   example: 42
 *       400:
- *         description: ID de projet invalide
+ *         $ref: '#/components/responses/BadRequest'
 *       500:
- *         description: Erreur serveur
+ *         $ref: '#/components/responses/ServerError'
 */
 router.delete('/projects/:id', ProjectController.deleteProject);