Résumé court

Quand on développe une API, le contrat OpenAPI finit souvent oublié dans un coin. Pourtant, c'est lui qui peut nous sauver : mocker avant de coder, lint la spec, tester la rétrocompatibilité, générer des collections de tests... Dans ce talk, je vous montre un workflow Contract-First expérimenté en entreprise, outillé avec des agents IA (Claude Code, Gemini CLI), pour que le contrat devienne le point de départ et pas un livrable de fin de sprint.

Résumé long

On aime toutes et tous avoir une "developer experience" heureuse, avec un contrat respecté et une documentation à jour... Pourtant, quand il s'agit de faire la même chose au quotidien, ça pêche parfois un peu (bien souvent parce que l'API n'est pas le produit).

"Quand est-ce que c'est dispo ?" "Est-ce que ce paramètre est obligatoire ?" "T'as pas un exemple ?"...

Tu développes une API et les développeurs web et mobile te pressent pour l'utiliser. Ils sont 3 ou 4, tu es seul. Eux créent des écrans tout beaux from scratch, et toi chaque ressource est le fruit d'appels à du legacy hétérogène... l'enfer !

Et si on apportait un peu de spec et d'autonomie à tout ce petit monde ?

Dans ce talk, on construit ensemble un workflow Contract-First complet, le même que j'utilise au quotidien en entreprise :

Le contrat comme source de vérité. Un fichier OpenAPI versionné, avec des exemples nommés qui servent à la fois de doc et de données de mock.

Importer une spec existante. Reverse-engineerer depuis un projet Spring Boot ou une URL, fusionner proprement, générer des exemples Microcks-ready.

Mocker avant de coder. Avec Microcks, les consommateurs bossent en autonomie dès le contrat posé. Routing sur le body JSON, simulation d'erreurs via headers, scripts Groovy pour les cas polymorphes.

Lint la spec comme on lint du code. Vacuum en continu : règles recommandées, OWASP, ruleset custom pour le legacy. Intégré en CI avec rapport HTML en commentaire de merge request.

Tester la rétrocompatibilité. Diff automatique avec openapi-diff sur les N dernières versions. Un breaking change dans un bump MINOR ? Le build casse.

Générer des collections de tests. Depuis le contrat, on génère une collection Bruno avec un safe merge qui préserve les scripts de test manuels.

Des agents IA comme accélérateurs. Chaque outil (import, lint, mock, génération Bruno) est encapsulé dans un skill d'agent IA (Claude Code, Gemini CLI) qui connaît le contexte du projet et enchaîne les étapes. Certains sont open-source sur skills.sh, comme microcks-local-server ou openapi-specification-v3.2.

Que ton API soit un produit ou un mal nécessaire, la production d'API sera bien plus propre après ce talk.

Ce que les participants vont apprendre

• Adopter une approche Contract-First même sur un projet legacy (exemple en Java majoritairement)

• Mocker avec Microcks piloté par le contrat OpenAPI

• Automatiser le linting (Vacuum) avec des rulesets adaptables

• Tester la rétrocompatibilité entre versions en CI/CD

• Générer des collections de tests (Bruno) depuis le contrat

• Utiliser des agents IA avec des skills publiés sur skills.sh