OpenAPI : linter, formater et structurer une API maintenable
operationId, tags, responses d'erreur : les règles qui évitent la dette sur vos specs OpenAPI.
Pourquoi linter et formater une spec OpenAPI avant de merger ?
Une spec peut passer la validation schéma tout en partant sans operationId, sans tags ou avec seulement une réponse default — et cette dette technique se manifeste des semaines plus tard quand les générateurs SDK, portails API ou tests de contrat échouent silencieusement. Le formatage seul ne comble pas ces lacunes ; le lint détecte des règles de style et de complétude que les validateurs ignorent. Le linter OpenAPI en ligne de FastMinify applique un sous-ensemble Spectral fixe sur les opérations de paths, entièrement dans le navigateur. Associez-le au formateur OpenAPI pour des diffs PR lisibles et au validateur OpenAPI pour la conformité schéma. Commencez par notre guide de validation OpenAPI si des erreurs structurelles vous bloquent, puis explorez le hub outils API.
Limites honnêtes et design d'API maintenable
Un statut lint passed signifie aucune issue dans le sous-ensemble v1 — pas que votre API est prête pour la production ou entièrement documentée.
Ces champs évitent une dette de spec que les validateurs manquent mais que générateurs et portails exigent.
operationId : stable, unique, camelCase — évitez les renommages sans plan de dépréciationtags : regroupement par domaine ou bounded context — aligné avec les sections du portail devinfo.description et info.contact : le lint warn si absents — remplissez pour les APIs externes/pet-orders à /petOrders — règle kebab-case alignée RESTLes outils navigateur accélèrent le feedback ; les pipelines imposent la politique org.
$ref externesDesign-first : valider, formater, puis linter
Ne permutez pas les étapes en revue — chaque outil répond à une question différente sur votre fichier OpenAPI.
Le lint FastMinify n'est pas Spectral complet — il livre un jeu de règles fixe centré sur des opérations de paths maintenables (ADR-OAS-009).
not-openapi (erreur) : la racine doit être OpenAPI 3.x avec un objet info — porte d'entrée avant les autres règlesinfo-contact (warning) : info.contact devrait être présentinfo-description (warning) : info.description non videpaths-kebab-case (warning) : segments de path en kebab-case ou vNoperation-operationId (warning) : chaque opération a un operationId non videoperation-tags (warning) : au moins un tag par opérationoperation-description (warning) : summary ou description requisoperation-success-response (erreur) : au moins une réponse 2xx — default seul ne suffit paspath-item-ref (warning) : $ref de path item non développée en lint v1Périmètre honnête — ne présumez pas de la parité avec Spectral, Redocly ou les moteurs de politique gateway.
webhooks et callbacks hors périmètre v1$ref externes — collez une spec autonomeLe formateur pretty-print en JSON ou YAML (indentation 2 ou 4 espaces) et peut trier les clés récursivement pour des diffs stables.
openapi: 3.0 numérique en YAML normalisé en chaîne 3.0.0Linter et formater OpenAPI : workflow pas à pas
Le linter OpenAPI parse JSON ou YAML (max 512 KiB), vérifie la porte not-openapi, puis exécute les règles sur les opérations. Statut : passed, passed with warnings ou failed — jamais un vert simple quand des warnings existent.
Le formateur OpenAPI pretty-print pour une revue humaine. Auto-format au collage ; bouton Format (⌘↵) après édition manuelle.
Votre pipeline mobile génère un client depuis la spec — les warnings ignorés deviennent des échecs en aval.
Étape 1 : Valider la conformité schéma
Collez dans validate-openapi. Corrigez d'abord les erreurs Scalar — le lint n'aide pas sur une spec structurellement invalide.
Étape 2 : Linter les opérations de paths
Ouvrez lint-openapi. Résolvez les warnings operation-operationId et operation-tags sur chaque endpoint public.
Étape 3 : Formater et ouvrir la PR
Passez la spec corrigée dans format-openapi avec tri des clés si l'équipe l'utilise. Re-lintez avant commit.
Un designer exporte du YAML minifié — les reviewers ne voient pas les renommages de paths accidentels.
Étape 1 : Formater pour la lisibilité
Collez dans format-openapi, indentation 2 espaces, tri des clés si l'équipe est d'accord.
Étape 2 : Valider puis linter
Validez avec Scalar, puis lintez pour paths-kebab-case et operation-success-response sur les nouveaux endpoints.
Étape 3 : Documenter les réponses d'erreur
Le lint impose la présence 2xx — ajoutez manuellement des 4xx/5xx avec descriptions pour des contrats production (hors erreurs lint v1).
Workflow revue PR : du design-first au merge
Traitez le trio navigateur comme porte rapide avant git push — la CI reste la source de vérité d'équipe, mais détecter localement économise des minutes de pipeline. Ordre : (1) validate-openapi — corriger les erreurs Scalar ; (2) format-openapi — diff lisible ; (3) lint-openapi — résoudre les erreurs, puis les warnings selon la politique d'équipe ; (4) commit.
Au-delà du validate vert, demandez : les operationId sont-ils uniques et stables pour le codegen ? Les tags correspondent-ils à la navigation du portail API ? Chaque opération documente-t-elle au moins une réponse succès — et les formes d'erreur courantes pour les équipes client ?
En CI, les équipes exécutent souvent Spectral, openapi-cli ou Redocly avec des rulesets plus stricts que FastMinify v1. Combinez le lint navigateur avec notre guide CI/CD. Pour les pivots de schéma : json-schema-to-openapi et openapi-to-json-schema sur le hub. Pour valider des payloads contre un schéma une fois le contrat sain : json-schema-validator (article dédié à venir).
Conclusion
Des specs OpenAPI maintenables exigent plus que la validation schéma : le lint attrape les lacunes operationId, tags et responses qui bloquent les générateurs, et le formatage garde les PR reviewables. Validez d'abord, formatez pour les humains, lintez pour le style — le tout localement avant la CI. Explorez le hub API pour la conversion JSON Schema et la validation SDL GraphQL quand votre travail de contrat dépasse le REST.
Articles connexes
Erreurs de schéma, $ref cassées, responses manquantes : validez votre contrat API OpenAPI 3.0–3.2 dans le navigateur.
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.