paths:
  /api/cms/articles:
    get:
      summary: Récupère la liste paginée des articles
      description: Retourne une liste paginée de tous les articles. L'authentification est optionnelle.
      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: 20
          description: Nombre d'articles par page
        - in: query
          name: search
          schema:
            type: string
          description: Terme de recherche pour les articles
      responses:
        '200':
          description: Liste des articles récupérée avec succès
          content:
            application/json:
              schema:
                type: object
                properties:
                  articles:
                    type: array
                    items:
                      $ref: '#/components/schemas/Article'
                  articlesCount:
                    type: integer
        '400':
          description: Erreur de validation
        '500':
          description: Erreur serveur

    post:
      summary: Crée un nouvel article
      description: Crée un nouvel article avec les données fournies. Authentification requise.
      tags:
        - Articles
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - article
              properties:
                article:
                  type: object
                  required:
                    - title
                    - description
                    - body
                  properties:
                    title:
                      type: string
                      example: "Titre de l'article"
                    description:
                      type: string
                      example: "Description courte"
                    body:
                      type: string
                      example: "Contenu complet de l'article"
                    tagList:
                      type: array
                      items:
                        type: string
                      example: ["tag1", "tag2"]
      responses:
        '201':
          description: Article créé avec succès
          content:
            application/json:
              schema:
                type: object
                properties:
                  article:
                    $ref: '#/components/schemas/Article'
        '400':
          description: Données invalides
        '401':
          description: Non authentifié
        '422':
          description: Erreur de validation des données

  /api/cms/articles/feed:
    get:
      summary: Récupère le fil d'actualité des articles
      description: Retourne les articles des utilisateurs suivis par l'utilisateur authentifié
      tags:
        - Articles
      security:
        - bearerAuth: []
      parameters:
        - in: query
          name: page
          schema:
            type: integer
            default: 1
          description: Numéro de page
        - in: query
          name: limit
          schema:
            type: integer
            default: 20
          description: Nombre d'articles par page
      responses:
        '200':
          description: Fil d'actualité récupéré avec succès
          content:
            application/json:
              schema:
                type: object
                properties:
                  articles:
                    type: array
                    items:
                      $ref: '#/components/schemas/Article'
                  articlesCount:
                    type: integer
        '401':
          description: Non authentifié
        '500':
          description: Erreur serveur

  /api/cms/articles/{slug}:
    get:
      summary: Récupère un article par son slug
      description: Retourne les détails complets d'un article spécifique
      tags:
        - Articles
      parameters:
        - in: path
          name: slug
          required: true
          schema:
            type: string
          description: Le slug unique de l'article
      responses:
        '200':
          description: Article récupéré avec succès
          content:
            application/json:
              schema:
                type: object
                properties:
                  article:
                    $ref: '#/components/schemas/Article'
        '404':
          description: Article non trouvé
        '500':
          description: Erreur serveur

    put:
      summary: Met à jour un article
      description: Met à jour un article existant. Seul l'auteur peut modifier son article. Authentification requise.
      tags:
        - Articles
      security:
        - bearerAuth: []
      parameters:
        - in: path
          name: slug
          required: true
          schema:
            type: string
          description: Le slug unique de l'article
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - article
              properties:
                article:
                  type: object
                  properties:
                    title:
                      type: string
                    description:
                      type: string
                    body:
                      type: string
                    tagList:
                      type: array
                      items:
                        type: string
      responses:
        '200':
          description: Article mis à jour avec succès
          content:
            application/json:
              schema:
                type: object
                properties:
                  article:
                    $ref: '#/components/schemas/Article'
        '401':
          description: Non authentifié
        '403':
          description: Vous n'êtes pas autorisé à modifier cet article
        '404':
          description: Article non trouvé
        '422':
          description: Erreur de validation des données

    delete:
      summary: Supprime un article
      description: Supprime un article existant. Seul l'auteur peut supprimer son article. Authentification requise.
      tags:
        - Articles
      security:
        - bearerAuth: []
      parameters:
        - in: path
          name: slug
          required: true
          schema:
            type: string
          description: Le slug unique de l'article
      responses:
        '200':
          description: Article supprimé avec succès
        '401':
          description: Non authentifié
        '403':
          description: Vous n'êtes pas autorisé à supprimer cet article
        '404':
          description: Article non trouvé
        '500':
          description: Erreur serveur

  /api/cms/articles/{slug}/favorite:
    post:
      summary: Ajoute un article aux favoris
      description: Ajoute un article à la liste des favoris de l'utilisateur authentifié
      tags:
        - Articles
      security:
        - bearerAuth: []
      parameters:
        - in: path
          name: slug
          required: true
          schema:
            type: string
          description: Le slug unique de l'article
      responses:
        '200':
          description: Article ajouté aux favoris avec succès
          content:
            application/json:
              schema:
                type: object
                properties:
                  article:
                    $ref: '#/components/schemas/Article'
        '401':
          description: Non authentifié
        '404':
          description: Article non trouvé
        '500':
          description: Erreur serveur

    delete:
      summary: Retire un article des favoris
      description: Retire un article de la liste des favoris de l'utilisateur authentifié
      tags:
        - Articles
      security:
        - bearerAuth: []
      parameters:
        - in: path
          name: slug
          required: true
          schema:
            type: string
          description: Le slug unique de l'article
      responses:
        '200':
          description: Article retiré des favoris avec succès
          content:
            application/json:
              schema:
                type: object
                properties:
                  article:
                    $ref: '#/components/schemas/Article'
        '401':
          description: Non authentifié
        '404':
          description: Article non trouvé
        '500':
          description: Erreur serveur

components:
  schemas:
    Article:
      type: object
      properties:
        slug:
          type: string
          description: Identifiant unique de l'article (généré à partir du titre)
          example: "mon-premier-article"
        title:
          type: string
          description: Titre de l'article
          example: "Mon Premier Article"
        description:
          type: string
          description: Description courte de l'article
          example: "Description courte pour le résumé"
        body:
          type: string
          description: Contenu complet de l'article
          example: "Contenu complet de l'article..."
        tagList:
          type: array
          items:
            type: string
          description: Liste des tags associés à l'article
          example: ["tag1", "tag2"]
        author:
          type: object
          properties:
            username:
              type: string
            image:
              type: string
            bio:
              type: string
            following:
              type: boolean
          description: Informations de l'auteur de l'article
        createdAt:
          type: string
          format: date-time
          description: Date/heure de création de l'article
          example: "2024-01-15T10:30:00Z"
        updatedAt:
          type: string
          format: date-time
          description: Date/heure de la dernière mise à jour
          example: "2024-01-15T10:30:00Z"
        favorited:
          type: boolean
          description: Indique si l'article est mis en favori par l'utilisateur authentifié
        favoritesCount:
          type: integer
          description: Nombre de fois que cet article a été ajouté aux favoris
          example: 5