OpenAPI (Swagger)

OpenAPI, anciennement connu sous le nom de Swagger, est une spécification open source permettant de décrire, produire, consommer et visualiser des services web RESTful. Elle fournit un format standardisé (YAML ou JSON) pour définir les endpoints, paramètres, réponses, authentification et modèles de données d'une API. Cette approche contract-first favorise la collaboration entre équipes et automatise de nombreux aspects du cycle de vie des APIs.

Fondements

• Spécification déclarative utilisant YAML ou JSON pour décrire l'intégralité d'une API REST
• Format machine-readable permettant la génération automatique de documentation, clients SDK et mocks
• Standard maintenu par l'OpenAPI Initiative (Linux Foundation) avec support massif de l'industrie
• Evolution du projet Swagger original, désormais séparé entre spécification (OpenAPI) et outils (Swagger)

Avantages

• Documentation automatique interactive et toujours synchronisée avec le code via Swagger UI
• Génération de clients SDK dans multiples langages (TypeScript, Java, Python, etc.) réduisant les erreurs d'intégration
• Validation des requêtes/réponses en développement et production pour garantir le respect du contrat
• Facilitation de l'approche design-first permettant de concevoir l'API avant l'implémentation
• Interopérabilité accrue grâce à un standard universel compris par tous les outils modernes d'API management

Exemple concret

openapi: 3.1.0
info:
  title: User Management API
  version: 1.0.0
  description: API for managing user accounts

paths:
  /users:
    get:
      summary: List all users
      parameters:
        - name: limit
          in: query
          schema:
            type: integer
            default: 20
            maximum: 100
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/User'
    post:
      summary: Create new user
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UserInput'
      responses:
        '201':
          description: User created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'

components:
  schemas:
    User:
      type: object
      required:
        - id
        - email
      properties:
        id:
          type: string
          format: uuid
        email:
          type: string
          format: email
        name:
          type: string
        createdAt:
          type: string
          format: date-time
    UserInput:
      type: object
      required:
        - email
      properties:
        email:
          type: string
          format: email
        name:
          type: string

Mise en œuvre

1. Choisir l'approche : design-first (écrire la spec avant le code) ou code-first (générer la spec depuis le code avec annotations)
2. Rédiger la spécification OpenAPI en définissant info, servers, paths, components et security schemes
3. Valider la spécification avec des outils comme Spectral ou l'éditeur Swagger pour détecter incohérences et non-conformités
4. Générer la documentation interactive avec Swagger UI ou ReDoc pour permettre l'exploration et le test de l'API
5. Générer les clients SDK pour les consommateurs et configurer la validation côté serveur avec express-openapi-validator ou similaire
6. Intégrer dans le CI/CD pour vérifier que l'implémentation respecte toujours le contrat OpenAPI
7. Publier dans un portail développeur ou registre d'APIs pour centraliser l'accès aux spécifications

Outils associés

• Swagger UI / ReDoc : génération de documentation interactive navigable depuis le navigateur
• Swagger Codegen / OpenAPI Generator : génération automatique de clients, serveurs et documentation
• Postman / Insomnia : import de specs OpenAPI pour tester les APIs avec auto-complétion
• Spectral / Vacuum : linters pour valider et appliquer des règles de style sur les spécifications
• Stoplight Studio : éditeur visuel collaboratif pour concevoir des APIs avec prévisualisation en temps réel
• Prism : serveur mock générant automatiquement des réponses réalistes depuis la spec OpenAPI

OpenAPI s'impose comme le standard incontournable pour documenter et gouverner les APIs REST modernes. En adoptant cette spécification, les organisations réduisent drastiquement le time-to-market des intégrations, améliorent la qualité du code grâce à la génération automatique, et facilitent la collaboration entre équipes frontend, backend et partenaires externes. L'investissement initial dans la rédaction d'une spécification OpenAPI de qualité se traduit par des gains exponentiels en productivité, maintenabilité et expérience développeur sur le long terme.