Documenter une API avec OpenAPI et Swagger

OpenAPI est le format standard pour décrire une API REST dans un fichier YAML ou JSON : ses adresses, ses méthodes, ses paramètres, la forme de ses requêtes et de ses réponses, ses codes d'erreur et son authentification. Swagger désigne aujourd'hui les outils qui exploitent ce fichier, dont Swagger UI, qui en tire une documentation interactive. Ce chapitre présente la structure d'un document OpenAPI 3.1, un exemple complet pour AppliFrais, les outils et les deux façons de travailler (la description d'abord, ou le code d'abord).

OpenAPI ou Swagger ?

Les deux noms désignent des choses liées mais différentes, et la confusion est fréquente.

• Swagger est né en 2011 comme format de description d'API, accompagné d'outils. Fin 2015, son éditeur, SmartBear, a confié le format à un consortium, l'OpenAPI Initiative (sous l'égide de la Linux Foundation), qui l'a renommé OpenAPI Specification (OAS) en 2016. La version 3.0, en 2017, est la première publiée sous ce nom.
• Swagger est resté le nom de la famille d'outils de l'éditeur SmartBear : Swagger UI (la documentation interactive), Swagger Editor (l'éditeur en ligne), Swagger Codegen (la génération de code).

Dire « la doc Swagger de mon API » reste courant et compris ; en toute rigueur, tu écris un document OpenAPI, que Swagger UI affiche.

Pour un nouveau projet, écris de l'OpenAPI 3.1 : c'est ce que ce chapitre utilise.

Pourquoi documenter avec OpenAPI

Une documentation écrite à la main dans un traitement de texte est fausse au bout de trois semaines. Un document OpenAPI est lisible par les machines, ce qui change tout :

• une documentation interactive générée automatiquement : chaque route, ses paramètres, des exemples, et un bouton pour l'essayer ;
• la validation automatique des requêtes et des réponses, à partir des schémas ;
• la génération de code : un client TypeScript, PHP ou C# prêt à l'emploi, ou le squelette du serveur ;
• un serveur simulé (mock) qui répond selon les exemples, pour que le front avance avant que l'API existe ;
• l'import dans les clients de test (Bruno, Postman, Insomnia), qui créent une requête par route ;
• un inventaire de toutes les routes exposées, utile pour la sécurité : ce qui n'est pas documenté ne devrait pas exister.

La structure d'un document OpenAPI

Un document OpenAPI est un objet YAML (ou JSON) dont les clés de premier niveau sont toujours les mêmes :

Un exemple complet : l'API d'AppliFrais

Voici un extrait réel du document OpenAPI d'AppliFrais, avec trois opérations. Lis-le en entier : chaque bloc est commenté juste après.

openapi: 3.1.2
info:
  title: API AppliFrais
  version: 1.4.0
  description: Gestion des fiches de frais des visiteurs médicaux du laboratoire GSB.
servers:
  - url: https://api.gsb.example/v1
    description: Production
  - url: http://localhost:3000/v1
    description: Poste du développeur
security:
  - jeton: []
tags:
  - name: Fiches
    description: Les fiches de frais mensuelles
paths:
  /fiches:
    get:
      tags: [Fiches]
      summary: Lister les fiches
      description: Un visiteur ne reçoit que ses fiches ; un comptable reçoit toutes les fiches.
      operationId: listerFiches
      parameters:
        - name: etat
          in: query
          schema:
            $ref: '#/components/schemas/Etat'
        - name: mois
          in: query
          schema:
            type: string
            pattern: '^\d{4}-(0[1-9]|1[0-2])$'
          example: '2026-10'
        - name: page
          in: query
          schema: { type: integer, minimum: 1, default: 1 }
        - name: limite
          in: query
          schema: { type: integer, minimum: 1, maximum: 100, default: 20 }
      responses:
        '200':
          description: Une page de fiches
          content:
            application/json:
              schema:
                type: object
                required: [donnees, pagination]
                properties:
                  donnees:
                    type: array
                    items:
                      $ref: '#/components/schemas/Fiche'
                  pagination:
                    $ref: '#/components/schemas/Pagination'
        '401':
          $ref: '#/components/responses/NonAuthentifie'
    post:
      tags: [Fiches]
      summary: Créer la fiche d'un mois
      operationId: creerFiche
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/NouvelleFiche'
      responses:
        '201':
          description: Fiche créée
          headers:
            Location:
              description: URI de la nouvelle fiche
              schema: { type: string }
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Fiche'
        '401':
          $ref: '#/components/responses/NonAuthentifie'
        '409':
          $ref: '#/components/responses/Conflit'
        '422':
          $ref: '#/components/responses/Invalide'
  /fiches/{id}:
    parameters:
      - name: id
        in: path
        required: true
        schema: { type: integer }
    get:
      tags: [Fiches]
      summary: Lire une fiche
      operationId: lireFiche
      responses:
        '200':
          description: La fiche
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Fiche'
        '401':
          $ref: '#/components/responses/NonAuthentifie'
        '404':
          $ref: '#/components/responses/Introuvable'
components:
  securitySchemes:
    jeton:
      type: http
      scheme: bearer
      bearerFormat: JWT
  schemas:
    Etat:
      type: string
      enum: [CR, CL, VA, MP]
      description: CR en cours de saisie, CL clôturée, VA validée, MP mise en paiement
    Fiche:
      type: object
      required: [id, visiteurId, mois, etat, montantValide]
      properties:
        id: { type: integer, readOnly: true }
        visiteurId: { type: integer, readOnly: true }
        mois: { type: string, example: '2026-10' }
        etat:
          $ref: '#/components/schemas/Etat'
        montantValide:
          type: [number, 'null']
          description: Fixé par le comptable à la validation
    NouvelleFiche:
      type: object
      required: [mois]
      additionalProperties: false
      properties:
        mois: { type: string, pattern: '^\d{4}-(0[1-9]|1[0-2])$' }
    Pagination:
      type: object
      properties:
        page: { type: integer }
        limite: { type: integer }
        total: { type: integer }
        pages: { type: integer }
    Probleme:
      type: object
      description: Erreur au format de la RFC 9457
      properties:
        type: { type: string, format: uri }
        title: { type: string }
        status: { type: integer }
        detail: { type: string }
        instance: { type: string }
  responses:
    NonAuthentifie:
      description: Jeton absent, invalide ou expiré
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/Probleme'
    Introuvable:
      description: Fiche inexistante ou appartenant à un autre visiteur
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/Probleme'
    Conflit:
      description: Une fiche existe déjà pour ce mois
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/Probleme'
    Invalide:
      description: Données invalides
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/Probleme'

Ce qu'il faut remarquer :

• servers donne l'adresse de base : le chemin /fiches se lit https://api.gsb.example/v1/fiches.
• security au premier niveau impose le jeton à toutes les opérations. Le schéma jeton, défini dans components.securitySchemes, est une authentification HTTP de type bearer avec un JWT (chapitre 9). Une route publique annulerait cette règle avec security: [].
• Les paramètres précisent leur emplacement (in: query pour la chaîne de requête, in: path pour un segment de l'URI comme {id}, in: header pour un en-tête), leur type et leurs contraintes : limite vaut 20 par défaut et 100 au maximum, comme décidé au chapitre 6.
• requestBody décrit le corps attendu ; responses décrit chaque code possible, avec son corps et ses en-têtes (le Location du 201).
• $ref réutilise un élément de components : le schéma Fiche est écrit une fois et utilisé par trois réponses ; les erreurs 401, 404, 409 et 422 partagent le schéma Probleme de la RFC 9457, avec le type application/problem+json.
• readOnly: true signale un champ que le serveur renvoie mais que le client n'envoie jamais (l'id).
• type: [number, 'null'] est la syntaxe d'OpenAPI 3.1 (héritée de JSON Schema) pour un champ qui peut valoir null. En OpenAPI 3.0, on écrivait nullable: true, qui n'existe plus en 3.1.
• additionalProperties: false sur NouvelleFiche refuse tout champ inattendu : la liste blanche, encore.

Afficher la documentation : Swagger UI, Redoc, Scalar

Le document OpenAPI n'est pas fait pour être lu tel quel par les développeurs qui utilisent l'API. Des outils le transforment en pages web :

La plupart des frameworks savent servir l'une de ces pages à partir du document OpenAPI, souvent à l'adresse /docs ou /swagger.

La description d'abord, ou le code d'abord ?

Deux façons de produire le document OpenAPI :

La description d'abord (design-first, ou API-first). On écrit le document OpenAPI avant le code, on le fait relire par l'équipe du front et par les utilisateurs de l'API, puis on code l'API pour qu'elle le respecte. Avantages : le contrat est discuté avant d'être figé dans le code, le front peut commencer tout de suite avec un serveur simulé, et les erreurs de conception coûtent moins cher à corriger. C'est l'approche recommandée pour une API utilisée par d'autres équipes ou d'autres entreprises.

Le code d'abord (code-first). On écrit l'API, puis on génère le document à partir du code, de ses annotations ou de ses commentaires. Avantage : le document ne peut pas diverger du code. Inconvénient : la conception se fait au fil du code, sans relecture du contrat.

Pour ton projet de BTS, les deux approches se défendent. L'important, devant le jury de l'E6, est que la documentation existe et soit à jour : montrer Swagger UI, essayer une route en direct et expliquer un schéma, c'est une démonstration convaincante de la compétence « rédiger la documentation technique ».

Les autres outils de l'écosystème

• Les éditeurs : Swagger Editor en ligne, ou l'extension OpenAPI de VS Code, qui valident le document au fil de la frappe et proposent l'autocomplétion.
• Les linters, comme Spectral : ils vérifient des règles de style (URI en minuscules, chaque opération a une description, chaque réponse d'erreur utilise application/problem+json) et s'intègrent à l'intégration continue.
• Les serveurs simulés, comme Prism : ils répondent aux requêtes en suivant les exemples et les schémas du document.
• Les générateurs de code, comme OpenAPI Generator : un client dans plus de quarante langages, ou un squelette de serveur.
• Les tests de contrat : des outils comme Schemathesis génèrent des requêtes à partir du document et vérifient que les réponses de l'API respectent les schémas (chapitre 11).

Le README de l'API

Le document OpenAPI décrit les routes. Un développeur qui découvre l'API a aussi besoin d'un README court qui répond aux questions que le document ne traite pas :

1. À quoi sert l'API, pour qui.
2. Comment obtenir un accès (un compte, une clé, un jeton) et s'authentifier, avec un exemple curl complet.
3. L'adresse de base de chaque environnement.
4. Les conventions communes : pagination, format des dates, format des erreurs, limites de débit.
5. Le lien vers la documentation interactive et vers le document OpenAPI.
6. La politique de versionnement et la liste des changements (changelog).
7. Comment lancer l'API en local, pour les développeurs de l'équipe.

Exercices

    delete:
      tags: [Fiches]
      summary: Supprimer une fiche en cours de saisie
      operationId: supprimerFiche
      responses:
        '204':
          description: Fiche supprimée
        '401':
          $ref: '#/components/responses/NonAuthentifie'
        '404':
          $ref: '#/components/responses/Introuvable'
        '409':
          description: La fiche n'est plus à l'état CR
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Probleme'

paths:
  /visiteurs/{id}:
    get:
      parameters:
        - name: id
          in: query
          schema: { type: integer }
      responses:
        200:
          description: Le visiteur
          content:
            application/json:
              schema:
                type: object
                properties:
                  telephone:
                    type: string
                    nullable: true