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

Votre contrat d'API réside probablement à trois endroits à la fois. Un diagramme dans un wiki. Une collection Postman exportée le trimestre dernier. Un document Markdown manuscrit qui s'est éloigné du service en cours d'exécution il y a deux versions. Quand ces trois-là sont en désaccord, votre équipe devine. Les devinettes brisent les intégrations.

Traiter votre spécification d'API comme du code corrige cela. Vous écrivez un fichier OpenAPI, le commettez dans Git et le révisez comme n'importe quel autre fichier source. À partir de ce fichier unique, vous générez des mocks, des tests, de la documentation et des SDK. La spécification cesse d'être une réflexion après coup et devient le contrat sur lequel tout le monde s'appuie.

Ce guide explique ce que signifie la "spécification comme code" (spec-as-code), pourquoi le fichier OpenAPI mérite la même rigueur que le code de votre application, et comment exécuter le flux de travail sans lutter contre vos outils.

Ce que signifie la spécification comme code

La spécification comme code signifie que votre définition d'API est un fichier texte brut qui réside dans le contrôle de version. Pas un enregistrement de base de données. Pas un document hébergé avec un lien de partage. Un fichier que vous pouvez `git diff`, brancher et fusionner.

L'idée est directement empruntée à la "documentation comme code" (docs-as-code), où la documentation se trouve dans le même dépôt que le code qu'elle décrit et est livrée via le même pipeline. La "spécification comme code" applique la même discipline au contrat d'API lui-même. Le document OpenAPI (YAML ou JSON) est l'artefact. Tout le reste en aval est généré à partir de celui-ci.

Ce changement a une conséquence majeure. La spécification devient la source unique de vérité. Lorsqu'un développeur veut savoir ce que `/users/{id}` retourne, il lit la spécification, pas une page wiki obsolète. Lorsque l'assurance qualité écrit un test, elle s'appuie sur la spécification. Lorsqu'un partenaire s'intègre, il extrait un SDK généré à partir de la spécification. Un seul fichier, de nombreuses sorties.

Pourquoi traiter la spécification comme du code

Une fois que la spécification est un fichier dans Git, vous héritez de tous les flux de travail auxquels vous faites déjà confiance pour le code source.

Revue dans les pull requests. Un changement à un endpoint apparaît comme un diff dans une PR. Les relecteurs voient exactement quels champs ont changé, quels codes de statut ont été ajoutés, et si la forme d'une réponse a cassé la compatibilité ascendante. Un changement cassant n'est plus une surprise en production. C'est un fil de commentaires avant la fusion. C'est le cœur d'un flux de travail API natif Git.

Format compatible avec les diffs. Les diffs YAML bruts sont propres. Vous pouvez lire un changement de cinq lignes et le comprendre en quelques secondes. Comparez cela à une exportation binaire ou à un outil hébergé où "ce qui a changé" est invisible. Avec la spécification dans Git, blame, l'historique et les diffs fonctionnent tous.

Versionnement réel. Chaque modification a un commit, un auteur et un horodatage. Vous pouvez étiqueter une version, créer une branche pour une refonte de `v2`, et annuler une mauvaise modification avec une seule commande. L'historique de votre API devient auditable. Pour un aperçu plus détaillé des stratégies d'étiquetage et de branchement, consultez le contrôle de version OpenAPI avec Git.

Source unique de vérité. Étant donné que les mocks, les tests et la documentation proviennent tous du même fichier, ils ne peuvent pas dériver indépendamment. Mettez à jour la spécification, régénérez, et chaque sortie reste cohérente.

Voici comment les deux approches se comparent en pratique.

OpenAPI comme artefact

OpenAPI est le format évident pour la spécification car il est largement pris en charge et lisible par machine. Voici un petit fragment complet d'un fichier OpenAPI 3.1 que vous conserveriez dans votre dépôt.

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. Ajoutez un champ à `Order`, et le diff n'est qu'une ligne. Modifiez l'énumération `status`, et un relecteur le voit instantanément. Gardez-le sous `api/openapi.yaml` à côté du code de votre service, et la spécification voyagera avec l'implémentation qu'elle décrit.

Spécification et documentation

L'avantage d'un fichier source unique est tout ce que vous en générez.

Mocks. Pointez un serveur de mock vers la spécification et vous obtenez une API exécutable avant même qu'un seul endpoint ne soit construit. Les équipes frontend et mobile commencent à s'intégrer au contrat dès le premier jour. Lorsque la spécification change, le mock change avec elle.

Tests. Générez des tests de contrat qui affirment que le service en direct correspond à la spécification. Si un endpoint déployé renvoie un champ que la spécification n'a jamais déclaré, le test échoue. Cela détecte les écarts entre le contrat et le code en cours d'exécution avant les clients.

Documentation. Rendez la spécification en documentation de référence automatiquement. Personne ne rédige plus de tables de points d'accès à la main. La documentation correspond à la spécification parce qu'elle est la spécification, rendue.

SDKs. Générez des bibliothèques clientes dans plusieurs langages à partir du même fichier. Les partenaires obtiennent un SDK typé qui reflète toujours le contrat actuel.

Chaque sortie est une fonction de la spécification. Changez l'entrée, régénérez les sorties, et la cohérence est gratuite.

Comment Apidog fait de la spécification la source de vérité

Exécuter la spécification comme code manuellement signifie assembler une CLI, un serveur de mock, un générateur de documentation et un hook Git. Apidog regroupe cela en un seul flux de travail.

Le mode Spec-First d'Apidog traite votre fichier OpenAPI comme la définition faisant autorité. Vous concevez des points de terminaison par rapport à la spécification, et Apidog maintient vos mocks, tests et documentation en parfaite synchronisation avec celle-ci.

La pièce qui rend cela pratique est la synchronisation bidirectionnelle de Git. Apidog peut lire votre fichier OpenAPI depuis un dépôt et réécrire les modifications, de sorte que le fichier dans Git et le projet dans Apidog restent en accord. Concevez visuellement lorsque c'est plus rapide, éditez directement le YAML lorsque c'est plus rapide, et les deux chemins aboutissent au même fichier committé. Cela maintient votre flux de révision de PR intact tout en offrant à votre équipe un éditeur plus riche. Pour les mécanismes de poussée des changements de spécification en amont, consultez comment synchroniser votre spécification OpenAPI avec GitHub.

Le résultat : le fichier OpenAPI reste la source unique de vérité, et les outils visuels se placent au-dessus de celui-ci plutôt que de le remplacer.

Pièges courants

La spécification comme code est simple, mais quelques pièges piègent les équipes très tôt.

Désynchronisation entre la spécification et l'implémentation. Rédiger la spécification ne suffit pas. Si rien ne vérifie que le service en cours d'exécution y correspond, les deux divergent silencieusement. Ajoutez des tests de contrat à l'intégration continue (CI) afin qu'un désaccord fasse échouer la construction, et non le client.

Confusion entre généré et manuscrit. Décidez si la spécification est générée à partir d'annotations de code ou manuscrite comme source. Mélanger les deux conduit à un fichier où personne ne sait quelle moitié est autoritaire. Choisissez une direction. Si la spécification est votre source de vérité, traitez les annotations de code comme ce que vous vérifiez par rapport à elle, pas comme une deuxième copie maîtresse.

Traiter la spécification comme de la documentation, et non comme un contrat. Une spécification que vous ne faites que lire est une documentation. Une spécification à partir de laquelle vous générez des mocks, des tests et des SDK est un contrat. La valeur provient du câblage des sorties, et non de l'existence du fichier.

Oubli de la revue. Une spécification dans Git qui fusionne sans revue n'est qu'un fichier dans Git. L'intérêt réside dans la pull request. Exigez une revue sur les changements de spécification de la même manière que pour le code.

Pour commencer

Vous pouvez adopter la spécification comme code de manière incrémentielle.

1. Commitez votre spécification. Déplacez votre fichier OpenAPI dans le dépôt à un chemin connu, comme `api/openapi.yaml`.
2. Exigez une revue de PR. Faites passer les changements de spécification par la même porte de revue que le code. Les diffs deviennent la conversation.
3. Générez une sortie. Commencez par des mocks ou de la documentation. Connectez la spécification à un générateur afin que la sortie se mette à jour lorsque le fichier le fait.
4. Ajoutez une vérification CI. Lint la spécification sur chaque PR. Détectez les OpenAPI invalides avant la fusion.
5. Bouclez la boucle avec des tests de contrat. Une fois que les mocks et la documentation sont fonctionnels, ajoutez des tests qui affirment que le service en direct correspond à la spécification.

Chaque étape est autonome. Vous obtenez de la valeur dès la première étape et la multipliez à chaque ajout.

Le changement est petit à décrire et grand en effet. Un fichier, dans Git, révisé comme du code, générant tout en aval. Si vous souhaitez que l'édition visuelle et la synchronisation Git soient intégrées, essayez le mode Spec-First d'Apidog et laissez le fichier OpenAPI rester votre 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 votre pipeline normal. La "documentation comme code" l'applique à la documentation. La "spécification comme code" l'applique au contrat d'API lui-même. En pratique, elles se renforcent mutuellement, car la documentation générée à partir d'une spécification validée est, par définition, de la "documentation comme code".

Quel format le fichier de spécification doit-il utiliser ?

OpenAPI en YAML est le choix courant. Le YAML se différencie proprement dans les pull requests et est lisible par les humains, tout en étant analysable par machine pour générer des mocks, des tests et des SDK. Le JSON fonctionne aussi, mais le YAML a tendance à produire des différences plus nettes.

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

Ajoutez des tests de contrat à la CI qui affirment que le service en cours d'exécution correspond à la spécification validée. Si un point de terminaison renvoie un champ non déclaré ou supprime un champ documenté, la construction échoue. Cette boucle de rétroaction est ce qui transforme la spécification d'un document d'espoir en un contrat appliqué.