La section paths

💡 Sujet

La section paths est le composant central d'OpenAPI. Elle définit tous les points de terminaison (endpoints) disponibles, les opérations HTTP et la logique de requête/réponse.

⚙️ Structure d'une route

Chaque clé sous paths est un chemin relatif à l'URL du serveur.

paths:
  /produits/{id}:
    get:
      summary: Récupère un produit par son ID
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: integer
      responses:
        '200':
          description: Succès
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Product'
        '404':
          description: Produit non trouvé

🛠️ Éléments d'une opération

• summary / description : Résumé court et explication détaillée.
• parameters : Liste des entrées (path, query, header, cookie).
• requestBody : Pour les méthodes POST/PUT, définit les données envoyées.
• responses : Liste les codes HTTP possibles et leur format de sortie.

🧩 Résumé

• Cœur de l'API : Décrit l'interaction réelle.
• Paramétrage : Typage fort des entrées pour une validation automatique.
• Réponses : Oblige à documenter les cas d'erreur (404, 500) en plus du succès.

🔗 Références

• OpenAPI Paths Object