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/measurementRoutes.js
+++ b/src/routes/measurementRoutes.js
@@ -7,14 +7,23 @@ const MeasurementController = require('../controllers/measurementController');
 * @swagger
 * /measurements:
 *   get:
+ *     tags:
+ *       - Mesures
 *     summary: Récupère toutes les mesures
+ *     description: Retourne la liste complète des mesures de tous les projets
 *     responses:
 *       200:
 *         description: Liste de toutes les mesures
+ *         content:
+ *           application/json:
+ *             schema:
+ *               type: array
+ *               items:
+ *                 $ref: '#/components/schemas/Measurement'
 *       404:
- *         description: Aucune mesure trouvée
+ *         $ref: '#/components/responses/NotFound'
 *       500:
- *         description: Erreur serveur
+ *         $ref: '#/components/responses/ServerError'
 */
 router.get('/measurements', MeasurementController.getAllMeasurements);

@@ -22,7 +31,10 @@ router.get('/measurements', MeasurementController.getAllMeasurements);
 * @swagger
 * /measurements/{id}:
 *   get:
+ *     tags:
+ *       - Mesures
 *     summary: Récupère une mesure par ID
+ *     description: Retourne les détails d'une mesure spécifique
 *     parameters:
 *       - in: path
 *         name: id
@@ -33,12 +45,16 @@ router.get('/measurements', MeasurementController.getAllMeasurements);
 *     responses:
 *       200:
 *         description: Détails de la mesure
+ *         content:
+ *           application/json:
+ *             schema:
+ *               $ref: '#/components/schemas/Measurement'
 *       400:
- *         description: ID de mesure invalide
+ *         $ref: '#/components/responses/BadRequest'
 *       404:
- *         description: Mesure non trouvée
+ *         $ref: '#/components/responses/NotFound'
 *       500:
- *         description: Erreur serveur
+ *         $ref: '#/components/responses/ServerError'
 */
 router.get('/measurements/:id', MeasurementController.getMeasurementById);

@@ -46,7 +62,10 @@ router.get('/measurements/:id', MeasurementController.getMeasurementById);
 * @swagger
 * /measurements/{projectId}/{orderId}:
 *   get:
+ *     tags:
+ *       - Mesures
 *     summary: Récupère une mesure par projet ID et ordre ID
+ *     description: Retourne les détails d'une mesure en fonction du projet et de son numéro d'ordre
 *     parameters:
 *       - in: path
 *         name: projectId
@@ -59,16 +78,20 @@ router.get('/measurements/:id', MeasurementController.getMeasurementById);
 *         required: true
 *         schema:
 *           type: integer
- *         description: ID d'ordre
+ *         description: ID d'ordre séquentiel de la mesure dans le projet
 *     responses:
 *       200:
 *         description: Détails de la mesure
+ *         content:
+ *           application/json:
+ *             schema:
+ *               $ref: '#/components/schemas/Measurement'
 *       400:
- *         description: IDs invalides
+ *         $ref: '#/components/responses/BadRequest'
 *       404:
- *         description: Mesure non trouvée
+ *         $ref: '#/components/responses/NotFound'
 *       500:
- *         description: Erreur serveur
+ *         $ref: '#/components/responses/ServerError'
 */
 router.get('/measurements/:projectId/:orderId', MeasurementController.getMeasurementByProjectAndOrderId);

@@ -76,23 +99,37 @@ router.get('/measurements/:projectId/:orderId', MeasurementController.getMeasure
 * @swagger
 * /measurements/{id}:
 *   delete:
+ *     tags:
+ *       - Mesures
 *     summary: Supprime une mesure
+ *     description: Supprime une mesure et l'image associée
 *     parameters:
 *       - in: path
 *         name: id
 *         required: true
 *         schema:
 *           type: integer
- *         description: ID de la mesure
+ *         description: ID de la mesure à supprimer
 *     responses:
 *       200:
 *         description: Mesure supprimée avec succès
+ *         content:
+ *           application/json:
+ *             schema:
+ *               type: object
+ *               properties:
+ *                 message:
+ *                   type: string
+ *                   example: Mesure supprimée avec succès
+ *                 id:
+ *                   type: integer
+ *                   example: 123
 *       400:
- *         description: ID de mesure invalide
+ *         $ref: '#/components/responses/BadRequest'
 *       404:
- *         description: Mesure non trouvée
+ *         $ref: '#/components/responses/NotFound'
 *       500:
- *         description: Erreur serveur
+ *         $ref: '#/components/responses/ServerError'
 */
 router.delete('/measurements/:id', MeasurementController.deleteMeasurement);