adastra_api/docs/SWAGGER_GUIDE.md

Guide Swagger - Documentation OpenAPI pour Adastra API

Accès à la documentation

Une fois le serveur lancé, accédez à : http://localhost:3200/api-docs

Exemple de documentation pour une route

Voici un exemple de comment documenter une GET route avec des paramètres de query :

/**
 * @swagger
 * /api/v1/articles:
 *   get:
 *     summary: Récupère la liste des articles
 *     description: Retourne une liste paginée de tous les articles
 *     tags:
 *       - Articles
 *     parameters:
 *       - in: query
 *         name: page
 *         schema:
 *           type: integer
 *           default: 1
 *         description: Numéro de page
 *       - in: query
 *         name: limit
 *         schema:
 *           type: integer
 *           default: 10
 *         description: Nombre d'articles par page
 *     responses:
 *       200:
 *         description: Liste des articles récupérée avec succès
 *         content:
 *           application/json:
 *             schema:
 *               type: object
 *               properties:
 *                 data:
 *                   type: array
 *                   items:
 *                     type: object
 *                     properties:
 *                       id:
 *                         type: integer
 *                       title:
 *                         type: string
 *                       content:
 *                         type: string
 *                 total:
 *                   type: integer
 *       400:
 *         description: Erreur de validation
 *       401:
 *         description: Non authentifié
 *       500:
 *         description: Erreur serveur
 */
router.get('/', async (req, res) => {
    // ... logique du contrôleur
});

Exemple avec POST et authentification

/**
 * @swagger
 * /api/v1/articles:
 *   post:
 *     summary: Crée un nouvel article
 *     description: Crée un nouvel article avec les données fournies
 *     tags:
 *       - Articles
 *     security:
 *       - bearerAuth: []
 *     requestBody:
 *       required: true
 *       content:
 *         application/json:
 *           schema:
 *             type: object
 *             required:
 *               - title
 *               - content
 *             properties:
 *               title:
 *                 type: string
 *                 example: "Mon Article"
 *               content:
 *                 type: string
 *                 example: "Contenu de l'article"
 *               tags:
 *                 type: array
 *                 items:
 *                   type: string
 *                 example: ["tag1", "tag2"]
 *     responses:
 *       201:
 *         description: Article créé avec succès
 *         content:
 *           application/json:
 *             schema:
 *               type: object
 *               properties:
 *                 id:
 *                   type: integer
 *                 title:
 *                   type: string
 *                 content:
 *                   type: string
 *       400:
 *         description: Données invalides
 *       401:
 *         description: Non authentifié
 */
router.post('/', authenticate, async (req, res) => {
    // ... logique du contrôleur
});

Exemple avec paramètres URL

/**
 * @swagger
 * /api/v1/articles/{id}:
 *   get:
 *     summary: Récupère un article par ID
 *     tags:
 *       - Articles
 *     parameters:
 *       - in: path
 *         name: id
 *         required: true
 *         schema:
 *           type: integer
 *         description: ID de l'article
 *     responses:
 *       200:
 *         description: Article récupéré avec succès
 *       404:
 *         description: Article non trouvé
 *       500:
 *         description: Erreur serveur
 */
router.get('/:id', async (req, res) => {
    // ... logique du contrôleur
});

Types de schémas courants

Objets simples

schema: {
  type: object
  properties:
    id: { type: integer }
    name: { type: string }
    email: { type: string, format: email }
    age: { type: integer, minimum: 0 }
    isActive: { type: boolean }
}

Arrays

schema: {
  type: array
  items:
    type: object
    properties:
      id: { type: integer }
      name: { type: string }
}

Enums

schema: {
  type: string
  enum: ["pending", "approved", "rejected"]
}

Tags disponibles

Les tags disponibles dans la config Swagger sont :

• Articles - Gestion des articles
• Users - Gestion des utilisateurs
• Products - Gestion des produits
• Clans - Gestion des clans
• Hero Wars - Données Hero Wars

Instructions générales

1. Placez les commentaires JSDoc directement au-dessus de la définition de la route
2. Utilisez le tag @swagger pour indiquer que c'est de la documentation OpenAPI
3. Commencez par le chemin d'accès : /api/v1/articles, /api/v1/articles/{id}, etc.
4. Spécifiez la méthode HTTP : get, post, put, delete, patch
5. Incluez toujours : summary, description, tags, responses
6. Pour les routes protégées, utilisez security: [{ bearerAuth: [] }] ou security: [{ apiKeyAuth: [] }]

Pour plus de détails

Consultez la documentation officielle : https://swagger.io/specification/

---

Note : Une fois que vous aurez ajouté les commentaires Swagger à vos routes, redémarrez le serveur et accédez à /api-docs pour voir la documentation mise à jour.