Valider une spec OpenAPI 3 / Swagger en ligne avant la CI
Erreurs de schéma, $ref cassées, responses manquantes : validez votre contrat API OpenAPI 3.0–3.2 dans le navigateur.
Pourquoi valider une spec OpenAPI avant de merger ?
Une spec OpenAPI invalide bloque les générateurs de clients, fait échouer les imports de passerelle API et retarde les revues de contrat. Pourtant, les erreurs les plus courantes — champ info incomplet, référence $ref interne cassée, version openapi non supportée — passent souvent inaperçues dans un diff YAML de plusieurs centaines de lignes. Le validateur OpenAPI en ligne de FastMinify vérifie la conformité schéma OpenAPI 3.0, 3.1 et 3.2 via @scalar/openapi-parser, entièrement dans le navigateur. Collez du JSON ou du YAML : le verdict, les chemins d'erreur et les statistiques de la spec s'affichent sans envoi serveur. Complétez avec le formateur OpenAPI pour une revue lisible, puis explorez le hub outils API. Si la syntaxe JSON brute est douteuse, commencez par le validateur JSON ; pour optimiser les payloads une fois le contrat validé, voir le guide d'optimisation des APIs REST.
Limites honnêtes et bonnes pratiques
Un verdict « valide » signifie conformité au schéma OpenAPI — pas que votre API répond correctement en production.
$ref externes ou URL distantesLes #/ references sont vérifiées par Scalar. Les références HTTP(S) vers d'autres fichiers ne sont jamais résolues — la spec doit être autonome pour une validation fiable dans le navigateur.
$ref externe non résolue peut passer le parse mais faillir ailleursL'outil navigateur accélère le feedback avant commit ; la CI reste la source de vérité pour les équipes.
git push — gain de temps vs pipeline completOpenAPI 3 vs Swagger 2 : ce que l'outil vérifie (et refuse)
OpenAPI 3.x décrit vos endpoints REST, schémas de requête/réponse, sécurité et composants réutilisables. FastMinify valide la conformité au meta-schéma OpenAPI — pas le comportement runtime de votre API.
3.0.x, 3.1.x, 3.2.xopenapi, info.title, info.version, pathsschemas, responses, parameters — références internes résoluesLes documents avec une clé racine swagger: "2.0" ne sont pas supportés par cet outil. Le message d'erreur est explicite — ne tentez pas de les valider ici.
swagger ; OpenAPI 3 utilise openapiAu-delà de la syntaxe, ce sont ces écarts structurels qui font planter la CI ou les générateurs SDK.
$ref interne pointant vers un composant inexistant — échec de validationdescription — règle OpenAPI non respectéeoperationId dupliqué ou absent — bloque certains générateurstype incompatible avec nullable / oneOf mal imbriquésTrois intentions distinctes sur le hub API — ne les confondez pas lors d'une revue de PR.
Valider une spec OpenAPI : workflow pas à pas
Le validateur OpenAPI parse l'entrée (JSON ou YAML, max 512 KiB), puis appelle Scalar validate(). Résultat : statut, première erreur avec ligne si connue, liste des issues avec chemins JSON Pointer.
Le formateur OpenAPI pretty-print en JSON ou YAML (indentation 2 ou 4 espaces, tri optionnel des clés). Utile pour une revue humaine — il ne remplace pas validate.
Vous exportez une spec depuis un outil de design et l'import AWS API Gateway / Kong échoue sans détail.
Étape 1 : Coller dans validate-openapi
Ouvrez validate-openapi. Si le parse échoue, corrigez d'abord la syntaxe JSON/YAML — le validateur JSON peut aider sur la partie JSON.
Étape 2 : Corriger les $ref internes
Les issues Scalar listent le chemin (#/components/schemas/User manquant, etc.). Corrigez la typo ou ajoutez le composant référencé.
Étape 3 : Formater et commit
Passez la spec validée dans format-openapi, téléchargez, ouvrez la PR. Réimportez dans la passerelle.
L'équipe mobile génère un client à partir de la spec — une erreur de schéma bloque tout le pipeline.
Étape 1 : Valider la version mergée
Collez la spec de la branche main dans validate-openapi. Verdict invalide → bloquez le tag de release.
Étape 2 : Vérifier info et paths
Champs info complets, chaque opération a des responses avec description. Les stats du panneau résultats aident à repérer des paths vides.
Étape 3 : Minifier les exemples JSON
Les exemples embarqués volumineux ralentissent les revues — utilisez le minificateur JSON sur les payloads d'exemple une fois la spec validée.
Conclusion
Valider une spec OpenAPI avant la CI évite des heures de debug sur des imports gateway ou des générateurs SDK silencieux. Collez, validez, corrigez les chemins Scalar — le tout localement. Formatez pour la revue, puis explorez le hub API pour lint, conversion JSON Schema et validation GraphQL.
Articles connexes
Config K8s, CI/CD, Ansible : convertissez JSON ↔ YAML sans perdre la structure ni les types.
Formatez, comparez deux réponses API et explorez un JSON profond — workflow debug sans extension IDE.
Virgules traînantes, guillemets simples, exports Excel : diagnostiquez et corrigez du JSON brisé avant qu'il n'atteigne la production.