Adding Swagger

2026-03-29 23:56:11 +02:00
parent fce91fa465
commit fe1bcc0ff7
11 changed files with 1883 additions and 16 deletions
@@ -0,0 +1,210 @@
+# 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 :
+
+```javascript
+/**
+ * @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
+
+```javascript
+/**
+ * @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
+
+```javascript
+/**
+ * @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
+```javascript
+schema: {
+  type: object
+  properties:
+    id: { type: integer }
+    name: { type: string }
+    email: { type: string, format: email }
+    age: { type: integer, minimum: 0 }
+    isActive: { type: boolean }
+}
+```
+
+### Arrays
+```javascript
+schema: {
+  type: array
+  items:
+    type: object
+    properties:
+      id: { type: integer }
+      name: { type: string }
+}
+```
+
+### Enums
+```javascript
+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.