Structure d'un fichier openapi.yaml

💡 Sujet

OpenAPI (anciennement Swagger) est la norme de description pour les API REST. Un fichier openapi.yaml permet de documenter les points d'entrée (endpoints), les paramètres, les formats de réponse et les schémas de données de manière standardisée.

🏗️ La structure de base

Un fichier OpenAPI se divise généralement en cinq sections principales :

openapi: 3.0.0
info:
  title: Mon API
  version: 1.0.0
servers:
  - url: https://api.exemple.com/v1
paths:
  /users:
    get:
      summary: Liste les utilisateurs
components:
  schemas:
    User:
      type: object

🔑 Les sections clés

📜 info

Contient les métadonnées de l'API : titre, description, version du contrat et informations de contact.

🌐 servers

Définit les URLs de base pour accéder à l'API (développement, staging, production).

🛣️ paths

C'est le cœur du fichier. On y définit chaque route, les méthodes HTTP associées (GET, POST, etc.), les paramètres d'entrée et les réponses possibles.

📦 components

Permet de définir des objets réutilisables (schémas de données, paramètres communs, réponses types) pour éviter la duplication.

🧩 Résumé

• Standardisation : Permet de générer de la documentation, des clients et des serveurs automatiquement.
• YAML : Format privilégié pour sa lisibilité par rapport au JSON.
• Modularité : Utilisation intensive de la section components pour maintenir un fichier propre.

🔗 Références

• OpenAPI Specification Official
• Swagger Editor