Design d'API Contract-First avec OpenAPI/Swagger, génération de code, validation de contrats et documentation interactive. À utiliser quand l'utilisateur conçoit une API REST, écrit une spécification OpenAPI ou génère du code depuis un contrat. Se déclenche aussi avec "OpenAPI", "Swagger", "contract first", "spécification API", "openapi.yaml", "swagger.json", "génération de code API". Also triggers on "contract-first API", "OpenAPI spec", "generate client from spec".
Instalar com Codex ou Claude Copie este prompt, cole no Codex, Claude ou outro assistente e deixe que ele revise a página da skill e instale para você.
Um comando direto ignora o prompt de revisão. Verifique a origem antes de executá-lo.
Instruções da origem · Visualização somente leitura
name
openapi-contract-first
description
Design d'API Contract-First avec OpenAPI/Swagger, génération de code, validation de contrats et documentation interactive. À utiliser quand l'utilisateur conçoit une API REST, écrit une spécification OpenAPI ou génère du code depuis un contrat. Se déclenche aussi avec "OpenAPI", "Swagger", "contract first", "spécification API", "openapi.yaml", "swagger.json", "génération de code API". Also triggers on "contract-first API", "OpenAPI spec", "generate client from spec".
Design API Contract-First avec OpenAPI
Workflow en étapes
Choisir la version OpenAPI — utiliser 3.1.0 pour tout nouveau projet (support JSON Schema complet, nullable remplacé par type: [string, 'null']). Rester sur 3.0.x uniquement si l'outillage cible ne supporte pas encore 3.1.
Rédiger la spec avant le code — commencer par les paths, les schemas required, les codes d'erreur. Ne pas générer la spec depuis le code existant : c'est du code-first déguisé.
Valider et linter la spec (Spectral) avant tout commit.
Faire reviewer par les consommateurs — frontend, mobile, partenaires — avant de freezer le contrat.
Générer serveur et/ou client depuis la spec validée.
Implémenter derrière le contrat généré ; l'implémentation ne doit jamais diverger du contrat.
Détecter les breaking changes en CI avant chaque PR mergée.
Publier la doc interactive (Swagger UI, Redoc, Scalar).
Générer la spec depuis code (code-first), puis migrer vers contract-first
Partenaires externes consomment l'API
Versionner dans l'URL (/v1/), publier Redoc/Scalar
Micro-changement non-breaking
OK sans bump de version majeure
Changement breaking (suppression champ, rename)
Nouvelle version (/v2/) + période de dépréciation
Authentification multi-schémas
Déclarer tous les securitySchemes, appliquer au niveau global ou opération
Garde-fous / Anti-patterns
Ne pas faire :
Générer la spec depuis le code annoté (code-first) puis prétendre faire du contract-first — la spec suit le code, pas l'inverse.
Schemas inline dans les paths — toujours utiliser $ref '#/components/schemas/...'.
Omettre operationId — les générateurs produiront des noms aléatoires et instables.
Marquer tous les champs response comme optionels par prudence — les clients ne sauront pas sur quoi compter.
Mettre des exemples incohérents avec les schemas (ne valident pas Spectral mais trompent les développeurs).
Versionner la spec dans le code applicatif sans pipeline de détection de breaking changes — un champ renommé casse silencieusement les clients.
Utiliser additionalProperties: false sur les requêtes mais pas sur les réponses — évolutivité compromise côté consommateur.
Pièges courants :
OpenAPI 3.1 utilise type: ['string', 'null'] ; nullable: true est 3.0 uniquement — mixer les deux casse les validateurs.
format: date-time est indicatif, pas contraignant — ajouter un pattern si la validation stricte est requise.
Les $ref dans les responses d'un path écrasent tout le contenu de la réponse (headers inclus) — déclarer les headers séparément si nécessaire.
Spectral extends: spectral:oas active les règles OAS3 et OAS2 — préciser extends: ['spectral:oas', {recommended: true}] pour filtrer.
Bonnes pratiques 2026
Scalar remplace Swagger UI comme UI de doc interactive standard (DX bien supérieure, thème moderne, Try-it intégré).
openapi-typescript v7+ génère des types avec paths, components, operations bien séparés — utiliser createFetch de openapi-fetch pour des appels typés bout-en-bout sans génération de client lourd.
Stocker la spec dans un dépôt dédié ou api/ à la racine du monorepo, versionné avec Git.
Taguer chaque release de spec avec la version (git tag api-v1.2.0).
Intégrer oasdiff en CI sur la branche principale pour bloquer les breaking changes non intentionnels.
Utiliser Prism pour mocker l'API depuis la spec pendant le développement frontend : npx @stoplight/prism-cli mock openapi.yaml.
Documenter les webhooks (OpenAPI 3.1 les supporte nativement via webhooks:).
