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/config/index.js
+++ b/src/config/index.js
@@ -29,16 +29,121 @@ module.exports = {
    definition: {
      openapi: '3.0.0',
      info: {
-        title: 'API Documentation',
+        title: 'API Timelapse',
        version: '1.0.0',
-        description: 'Documentation de l\'API avec Swagger'
+        description: 'Documentation de l\'API Timelapse pour la gestion des projets, mesures et vidéos',
+        contact: {
+          name: 'Support Timelapse',
+          email: 'support@timelapse.kerboul.me'
+        }
      },
      servers: [
-        { url: 'https://timelapse.kerboul.me/api' },
-        { url: 'http://localhost:3000/api' }
-      ]
+        { url: 'https://timelapse.kerboul.me/api', description: 'Serveur de production' },
+        { url: 'http://localhost:3000/api', description: 'Serveur de développement local' }
+      ],
+      components: {
+        schemas: {
+          Project: {
+            type: 'object',
+            properties: {
+              id: { type: 'integer' },
+              name: { type: 'string' },
+              description: { type: 'string' },
+              start_date: { type: 'string', format: 'date' },
+              status: { type: 'integer' }
+            }
+          },
+          Measurement: {
+            type: 'object',
+            properties: {
+              id: { type: 'integer' },
+              project_id: { type: 'integer' },
+              timestamp: { type: 'string', format: 'date-time' },
+              path: { type: 'string' },
+              temperature: { type: 'number' },
+              humidity: { type: 'number' },
+              order_id: { type: 'integer' }
+            }
+          },
+          Video: {
+            type: 'object',
+            properties: {
+              id: { type: 'integer' },
+              project_id: { type: 'integer' },
+              measurement_ids: { type: 'string' },
+              name: { type: 'string' },
+              resolution: { type: 'string' },
+              duration: { type: 'integer' },
+              status: { type: 'integer' },
+              progress: { type: 'number' },
+              video_file: { type: 'string', nullable: true },
+              started_at: { type: 'string', format: 'date-time', nullable: true },
+              updated_at: { type: 'string', format: 'date-time', nullable: true },
+              eta: { type: 'number', nullable: true }
+            }
+          },
+          Camera: {
+            type: 'object',
+            properties: {
+              id: { type: 'integer' },
+              interval: { type: 'integer', nullable: true },
+              maintenance: { type: 'integer' },
+              active: { type: 'integer' }
+            }
+          },
+          Error: {
+            type: 'object',
+            properties: {
+              message: { type: 'string' },
+              statusCode: { type: 'integer' },
+              details: { type: 'string', nullable: true },
+              timestamp: { type: 'string', format: 'date-time' }
+            }
+          }
+        },
+        responses: {
+          NotFound: {
+            description: 'La ressource demandée n\'a pas été trouvée',
+            content: {
+              'application/json': {
+                schema: {
+                  $ref: '#/components/schemas/Error'
+                }
+              }
+            }
+          },
+          BadRequest: {
+            description: 'Requête invalide',
+            content: {
+              'application/json': {
+                schema: {
+                  $ref: '#/components/schemas/Error'
+                }
+              }
+            }
+          },
+          ServerError: {
+            description: 'Erreur serveur',
+            content: {
+              'application/json': {
+                schema: {
+                  $ref: '#/components/schemas/Error'
+                }
+              }
+            }
+          }
+        }
+      },
+      tags: [
+        { name: 'Projets', description: 'Opérations relatives aux projets' },
+        { name: 'Mesures', description: 'Opérations relatives aux mesures et images' },
+        { name: 'Vidéos', description: 'Opérations relatives aux vidéos' },
+        { name: 'Caméra', description: 'Opérations relatives au contrôle de la caméra' },
+        { name: 'Images', description: 'Opérations relatives aux images' },
+        { name: 'Système', description: 'Opérations relatives au système' }
+      ],
    },
-    apis: ['./src/routes/*.js', './src/controllers/*.js'] // Chemins pour la documentation
+    apis: ['./src/routes/*.js'] // Chemins pour la documentation
  },
  
  // Chemins des répertoires