Traiter sa Spécification API comme du Code: Pourquoi et Comment

Votre contrat d’API réside souvent à trois endroits : un diagramme dans un wiki, une collection Postman exportée il y a quelques mois, et un fichier Markdown qui ne correspond plus au service déployé. Dès que ces sources divergent, l’équipe devine. Et les devinettes cassent les intégrations.

Essayez Apidog aujourd’hui

Traiter votre spécification d’API comme du code corrige ce problème. Vous écrivez un fichier OpenAPI, vous le commitez dans Git, puis vous le relisez comme n’importe quel autre fichier source. À partir de ce fichier unique, vous pouvez générer des mocks, des tests, de la documentation et des SDK.

Ce guide montre comment appliquer une approche spec-as-code avec OpenAPI, Git, la CI et des outils comme Apidog, sans transformer votre workflow API en usine à gaz.

Ce que signifie la spécification comme code

La spécification comme code signifie que votre définition d’API est un fichier texte versionné dans Git.

Pas un document partagé.

Pas une base de données propriétaire.

Pas une collection exportée manuellement.

Un fichier que vous pouvez :

• lire ;
• modifier ;
• git diff ;
• relire en pull request ;
• taguer ;
• annuler avec git revert.

L’approche reprend les principes de la documentation comme code : l’artefact vit dans le même dépôt que le système qu’il décrit et passe par le même pipeline.

Dans le cas d’une API, l’artefact principal est le fichier OpenAPI, généralement en YAML ou JSON.

Tout le reste est généré à partir de ce fichier :

• mocks ;
• tests de contrat ;
• documentation ;
• SDK ;
• collections de test ;
• références publiques ou internes.

La conséquence est importante : la spécification devient la source unique de vérité.

Si un développeur veut savoir ce que retourne GET /users/{id}, il lit la spec.

Si la QA écrit un test, elle s’appuie sur la spec.

Si un partenaire consomme l’API, il utilise une documentation ou un SDK généré depuis la spec.

Pourquoi traiter la spécification comme du code

Dès que la spécification est dans Git, vous récupérez les workflows que vous utilisez déjà pour le code applicatif.

1. Relire les changements en pull request

Un changement d’endpoint devient un diff lisible.

Exemple :

 status:
   type: string
-  enum: [pending, shipped, delivered]
+  enum: [pending, shipped, delivered, cancelled]

Un reviewer voit immédiatement qu’un nouveau statut est ajouté.

Même chose pour :

• un champ supprimé ;
• un code HTTP ajouté ;
• un schéma de réponse modifié ;
• un paramètre devenu obligatoire ;
• un changement potentiellement cassant.

Un breaking change n’apparaît plus par surprise en production. Il est discuté avant la fusion.

C’est le principe d’un flux de travail API natif Git.

2. Obtenir des diffs propres

Un fichier YAML est facile à comparer.

Vous pouvez comprendre une modification de quelques lignes sans ouvrir un outil externe. Git garde aussi :

• l’historique ;
• les auteurs ;
• les dates ;
• les branches ;
• les tags ;
• le blame.

Avec une spécification exportée depuis un outil hébergé, ces informations sont souvent difficiles à exploiter.

3. Versionner réellement votre API

Chaque modification de contrat devient un commit.

Vous pouvez par exemple :

git tag api-v1.2.0
git checkout -b api-v2-redesign
git revert <commit>

Cela rend l’évolution de l’API auditable et réversible.

Pour aller plus loin sur les stratégies de branches et de tags, consultez le guide sur le contrôle de version OpenAPI avec Git.

4. Garder les sorties synchronisées

Si les mocks, les tests et la documentation viennent tous du même fichier, ils ne dérivent pas séparément.

Le workflow devient :

1. modifier api/openapi.yaml ;
2. relire la PR ;
3. valider la spec ;
4. régénérer les sorties ;
5. déployer.

Comparaison pratique :

Préoccupation	Spécification dans un outil hébergé	Spécification d’API comme code
Revue des changements	Manuelle, facile à manquer	Diff de PR, revue bloquante
Historique	Limité ou lié au fournisseur	Journal Git complet
Rollback	Souvent manuel	git revert
Source de vérité	Ambiguë	Le fichier commité
Intégration CI	Add-on	Native

OpenAPI comme artefact principal

OpenAPI est le format le plus adapté pour cette approche, car il est :

• standardisé ;
• lisible par les humains ;
• exploitable par les machines ;
• pris en charge par de nombreux générateurs et outils de test.

Voici un exemple minimal de fichier OpenAPI 3.1 que vous pouvez conserver dans api/openapi.yaml :

openapi: 3.1.0
info:
  title: Orders API
  version: 1.2.0

paths:
  /orders/{orderId}:
    get:
      summary: Get an order by ID
      operationId: getOrder
      parameters:
        - name: orderId
          in: path
          required: true
          schema:
            type: string
            format: uuid
      responses:
        "200":
          description: The requested order
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Order"
        "404":
          description: Order not found

components:
  schemas:
    Order:
      type: object
      required:
        - id
        - status
        - total
      properties:
        id:
          type: string
          format: uuid
        status:
          type: string
          enum:
            - pending
            - shipped
            - delivered
        total:
          type: number
          format: float

Ce fichier est le contrat.

Si vous ajoutez un champ à Order, le diff est explicite.

Si vous modifiez l’énumération status, la PR le montre.

Si vous supprimez une réponse 404, le reviewer le voit.

Un emplacement simple fonctionne bien :

.
├── api
│   └── openapi.yaml
├── src
├── tests
└── package.json

L’objectif est que la spécification voyage avec le service qu’elle décrit.

Générer des sorties depuis la spécification

La valeur de la spec-as-code vient de ce que vous branchez dessus.

Mocks

Un serveur de mock peut exposer une API conforme à la spécification avant même que l’implémentation soit terminée.

Cela permet aux équipes frontend ou mobile de commencer à intégrer :

GET /orders/7d6f8f4a-8c29-4e37-9b8c-45a21d8e9a10

sans attendre que le backend soit finalisé.

Quand la spécification change, le mock change aussi.

Tests de contrat

Les tests de contrat vérifient que le service en cours d’exécution respecte le fichier OpenAPI.

Par exemple, si la spec annonce :

required:
  - id
  - status
  - total

mais que l’API renvoie :

{
  "id": "7d6f8f4a-8c29-4e37-9b8c-45a21d8e9a10",
  "status": "shipped"
}

le test doit échouer, car total manque.

Cette vérification évite que la spec devienne une documentation théorique sans lien avec la production.

Documentation

La documentation de référence peut être générée directement depuis OpenAPI.

Vous n’avez plus besoin de maintenir à la main :

• les routes ;
• les paramètres ;
• les exemples de réponse ;
• les codes HTTP ;
• les schémas JSON.

La documentation reste alignée parce qu’elle est le rendu de la spécification.

SDK

Les SDK clients peuvent être générés depuis le même fichier.

Cela permet de fournir aux consommateurs de l’API des clients typés dans plusieurs langages, toujours alignés sur le contrat courant.

Chaque sortie est une fonction de la spécification. Changez l’entrée, régénérez, et vous gardez la cohérence.

Ajouter une vérification CI minimale

Une première étape simple consiste à valider la spec à chaque pull request.

Exemple de workflow GitHub Actions :

name: Validate OpenAPI

on:
  pull_request:
    paths:
      - "api/openapi.yaml"

jobs:
  lint-openapi:
    runs-on: ubuntu-latest

    steps:
      - name: Checkout
        uses: actions/checkout@v4

      - name: Install Redocly CLI
        run: npm install -g @redocly/cli

      - name: Lint OpenAPI
        run: redocly lint api/openapi.yaml

Ce type de check permet de bloquer les erreurs évidentes avant la fusion :

• YAML invalide ;
• $ref cassé ;
• schéma incomplet ;
• opération mal définie ;
• réponse absente.

Ensuite, vous pouvez ajouter des tests de contrat pour comparer la spec au service réellement lancé.

Comment Apidog garde la spécification comme source de vérité

Mettre en place la spec-as-code à la main implique souvent de combiner plusieurs éléments :

• un éditeur OpenAPI ;
• une CLI de validation ;
• un serveur de mock ;
• un générateur de documentation ;
• des tests de contrat ;
• une synchronisation Git.

Apidog regroupe ces étapes dans un workflow orienté spécification.

Le mode Spec-First d’Apidog traite votre fichier OpenAPI comme la définition faisant autorité. Vous concevez vos endpoints par rapport à cette spécification, puis les mocks, tests et documentations restent synchronisés avec elle.

Le point clé est la synchronisation bidirectionnelle avec Git.

Apidog peut lire votre fichier OpenAPI depuis un dépôt et réécrire les modifications. Cela permet de garder alignés :

• le fichier dans Git ;
• le projet dans Apidog ;
• la documentation ;
• les mocks ;
• les tests.

Vous pouvez donc :

• éditer visuellement quand c’est plus rapide ;
• modifier directement le YAML quand c’est plus précis ;
• conserver la revue de PR comme étape obligatoire.

Pour les détails de synchronisation, consultez le guide sur comment synchroniser votre spécification OpenAPI avec GitHub.

Le résultat : OpenAPI reste la source unique de vérité, et l’outil visuel se place au-dessus du fichier au lieu de le remplacer.

Pièges courants

La spec-as-code est simple à comprendre, mais certaines erreurs reviennent souvent.

1. Ne pas vérifier l’implémentation

Écrire une spécification ne suffit pas.

Si rien ne vérifie que le service déployé correspond au fichier OpenAPI, les deux peuvent diverger silencieusement.

Action recommandée :

• valider la spec en CI ;
• lancer le service en environnement de test ;
• exécuter des tests de contrat contre l’API réelle.

2. Mélanger spec générée et spec manuscrite

Vous devez choisir la source principale.

Deux modèles existent :

• la spec est écrite à la main et l’implémentation doit la respecter ;
• la spec est générée depuis le code.

Les deux peuvent fonctionner, mais les mélanger crée de la confusion. Si OpenAPI est votre source de vérité, ne laissez pas des annotations de code devenir une deuxième source maîtresse.

3. Traiter la spec comme une simple documentation

Une spécification que vous lisez seulement est une documentation.

Une spécification qui génère des mocks, des tests, des SDK et de la documentation devient un contrat opérationnel.

La valeur vient du câblage.

4. Fusionner sans revue

Une spec dans Git sans revue reste seulement un fichier dans Git.

Ajoutez des règles de protection :

• revue obligatoire ;
• validation OpenAPI obligatoire ;
• tests de contrat si possible ;
• interdiction de merger directement sur la branche principale.

Workflow de démarrage

Vous pouvez adopter la spécification comme code progressivement.

Étape 1 : commiter la spécification

Placez votre fichier OpenAPI dans le dépôt :

api/openapi.yaml

Commitez-le avec le service concerné.

Étape 2 : imposer la revue de PR

Chaque changement de contrat doit passer par une pull request.

Les diffs deviennent le support de discussion entre backend, frontend, QA et consommateurs de l’API.

Étape 3 : générer une première sortie

Commencez par une sortie simple :

• documentation ;
• mock ;
• collection de test ;
• SDK interne.

L’objectif est de rendre le fichier utile immédiatement.

Étape 4 : ajouter une validation CI

Ajoutez un lint OpenAPI sur chaque PR.

Même une vérification minimale détecte rapidement les erreurs structurelles.

Étape 5 : ajouter des tests de contrat

Une fois la spec stable, comparez le service réel au contrat OpenAPI.

Cela ferme la boucle entre :

• le fichier ;
• l’implémentation ;
• la documentation ;
• les consommateurs.

Conclusion

Le changement est simple : un fichier OpenAPI, dans Git, relu comme du code, utilisé pour générer tout ce qui dépend du contrat API.

Ce workflow réduit les divergences entre documentation, tests, mocks et implémentation. Il rend aussi les changements d’API visibles avant qu’ils ne cassent les intégrations.

Si vous voulez combiner édition visuelle, workflow Git et synchronisation OpenAPI, essayez le mode Spec-First d’Apidog et gardez votre fichier OpenAPI comme source unique de vérité.

FAQ

La “spécification d’API comme code” est-elle la même chose que la “documentation comme code” ?

Elles partagent la même philosophie : conserver l’artefact sous contrôle de version et le livrer via le pipeline habituel.

La documentation comme code concerne la documentation.

La spécification comme code concerne le contrat API lui-même.

En pratique, elles se renforcent : une documentation générée depuis une spécification validée est aussi de la documentation comme code.

Quel format utiliser pour le fichier de spécification ?

OpenAPI en YAML est le choix courant.

Le YAML se lit bien dans les pull requests, produit des diffs propres et reste exploitable par les outils pour générer des mocks, tests, documentations et SDK.

JSON fonctionne aussi, mais les diffs YAML sont souvent plus lisibles.

Comment empêcher la spécification de s’éloigner de l’API réelle ?

Ajoutez des tests de contrat dans la CI.

Ils doivent vérifier que le service en cours d’exécution respecte la spécification validée. Si un endpoint renvoie un champ non déclaré, supprime un champ obligatoire ou change la forme d’une réponse, le build doit échouer.

C’est cette boucle qui transforme la spécification en contrat appliqué, et non en document d’intention.