benoit-bremaud / safebase-simplified

Projet Safebase simplifié
MIT License
0 stars 0 forks source link

### **GitHub Issue: Automatisation de la Documentation pour la Route `databaseRoutes`** #10

Open benoit-bremaud opened 1 week ago

benoit-bremaud commented 1 week ago

Résumé

Implémenter une documentation automatique pour l’API databaseRoutes afin de rendre accessible et compréhensible chaque opération CRUD de gestion de bases de données. Utiliser Fastify Swagger pour générer une documentation interactive au format OpenAPI et JSDoc pour générer des documents statiques basés sur les docstrings.

Contexte

L’ajout d’une documentation automatique permettra aux développeurs de mieux comprendre et utiliser l’API, en particulier pour la gestion des bases de données. La documentation Swagger sera consultable en ligne, tandis que JSDoc fournira une référence statique générée à partir des docstrings.

Objectifs


Tâches

  1. Installation et Configuration de Fastify Swagger

    • Ajouter les dépendances Swagger :
      npm install @fastify/swagger @fastify/swagger-ui
    • Configurer Swagger dans server.js pour générer une documentation accessible à l’endpoint /documentation.
    • Configurer les informations générales de Swagger (titre, description, version de l’API).
  2. Ajout de Métadonnées Swagger aux Routes dans databaseRoutes.js

    • Ajouter des métadonnées Swagger pour chaque route CRUD (POST, GET, PUT, DELETE) pour décrire :
      • Les paramètres attendus (e.g., databaseName).
      • Les réponses attendues (e.g., 201 pour création réussie, 400 pour des erreurs de validation).
    • Exemple pour la route POST /databaseRoutes :
      fastify.post('/databaseRoutes', {
      schema: {
       description: 'Create a new database',
       body: {
         type: 'object',
         required: ['databaseName'],
         properties: {
           databaseName: { type: 'string', description: 'Name of the database to create' },
         },
       },
       response: {
         201: { type: 'object', properties: { message: { type: 'string' } } },
         400: { type: 'object', properties: { error: { type: 'string' } } },
         500: { type: 'object', properties: { error: { type: 'string' }, details: { type: 'string' } } },
       },
      },
      }, async (request, reply) => {
      // Logique de création de la base de données...
      });
  3. Configuration de JSDoc

    • Installer JSDoc en tant que dépendance globale ou locale :
      npm install -g jsdoc
    • Créer un fichier de configuration jsdoc.json dans le répertoire racine pour générer la documentation dans un dossier docs :
      {
      "source": {
       "include": ["src"],
       "includePattern": ".js$",
       "excludePattern": "(node_modules/|docs)"
      },
      "opts": {
       "destination": "./docs",
       "recurse": true
      }
      }
  4. Ajout de Docstrings pour JSDoc dans databaseRoutes.js

    • Ajouter des docstrings détaillés pour chaque fonction CRUD dans databaseRoutes.js.
    • Les docstrings doivent inclure des descriptions des paramètres (databaseName, currentName, newName) et des messages de réponse pour JSDoc.
    • Exemple pour registerDatabaseRoutes :
      /**
      * Register CRUD routes for managing databases on the MySQL server.
      * 
      * @function registerDatabaseRoutes
      * @param {Object} fastify - The Fastify instance to register routes on.
      * @description Handles CRUD operations for databases, including creating, listing,
      *              renaming, and deleting databases on the MySQL server.
      */
  5. Génération et Vérification de la Documentation

    • Démarrer le serveur et vérifier la documentation Swagger à l’URL http://localhost:3000/documentation.
    • Générer la documentation JSDoc :
      jsdoc -c jsdoc.json
    • Ouvrir le dossier docs et vérifier que la documentation est générée correctement.

Critères d’acceptation

Ressources