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 :

```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.