
OpenAPI : linter, formater et structurer une API maintenable
operationId, tags, responses d'erreur : les règles qui évitent la dette quand vous lintez et formatez vos specs OpenAPI.
Linter et formater une spécification OpenAPI avant la fusion
Une spécification peut passer la validation du schéma et partir quand même sans operationId, sans tags ou avec seulement une réponse default. Cette dette technique se manifeste des semaines plus tard, quand les générateurs de SDK, les portails d'API ou les tests de contrat échouent en silence. Le formatage seul ne comble pas ces lacunes, alors que le lint détecte les règles de style et de complétude que les validateurs ignorent. Le linter OpenAPI en ligne de FastMinify applique un sous-ensemble fixe de type Spectral aux opérations des chemins, entièrement dans le navigateur. Associez-le au formateur OpenAPI pour des diffs de PR lisibles et au validateur OpenAPI pour la conformité au schéma. Si des erreurs structurelles vous bloquent d'abord, commencez par notre guide de validation OpenAPI, puis explorez le hub outils API.
Limites honnêtes et conception d'API maintenable
Un résultat Aucun problème bloquant signifie qu'aucun problème n'apparaît dans le sous-ensemble de règles v1, pas que votre API est prête pour la production ou entièrement documentée.
Ces champs évitent une dette de spécification que les validateurs ratent, mais que les générateurs et les portails exigent.
operationId : stable, unique, en camelCase, et jamais renommé sans plan de dépréciationtags : regroupement par domaine fonctionnel, aligné sur les sections du portail développeurinfo.description et info.contact : le lint avertit s'ils sont absents, remplissez-les pour les API externes/pet-orders à /petOrders, car la règle kebab-case s'aligne sur les conventions RESTLes outils du navigateur accélèrent le retour, et les pipelines imposent la politique de l'organisation.
$ref externesValider, formater puis linter, dans l'ordre design-first
Ne permutez pas les étapes pendant la relecture : chaque outil répond à une question différente sur votre fichier OpenAPI.
Le lint de FastMinify n'est pas Spectral au complet. Il livre un jeu de règles fixe centré sur des opérations de chemins maintenables (ADR-OAS-009).
not-openapi (erreur) : la racine doit être OpenAPI 3.x avec un objet info, comme contrôle d'entrée avant les autres règlesinfo-contact (avertissement) : info.contact devrait être présentinfo-description (avertissement) : info.description non videpaths-kebab-case (avertissement) : segments de chemin en kebab-case ou vNoperation-operationId (avertissement) : chaque opération a un operationId non videoperation-tags (avertissement) : au moins un tag par opérationoperation-description (avertissement) : summary ou description requisoperation-success-response (erreur) : au moins une réponse 2xx, default seul ne suffit paspath-item-ref (avertissement) : $ref d'un path item non développée en lint v1Un périmètre honnête : ne présumez pas d'une parité avec Spectral, Redocly ou les moteurs de politique des passerelles.
webhooks et callbacks sont hors périmètre en v1$ref externes : collez une spécification autonomeLe formateur réécrit le JSON ou le YAML avec une indentation de 2 ou 4 espaces et peut trier les clés de façon récursive pour des diffs stables.
openapi: 3.0 numérique en YAML est normalisé en chaîne 3.0.0Linter et formater OpenAPI pas à pas
Le linter OpenAPI analyse du JSON ou du YAML (512 KiB au plus), vérifie la règle d'entrée not-openapi, puis exécute les règles sur les opérations. Le résultat indique Aucun problème bloquant, Valide avec avertissements ou Problèmes bloquants détectés, et il n'est jamais un simple vert quand des avertissements existent.
Le formateur OpenAPI réécrit le document pour une relecture humaine. Il formate automatiquement au collage, et le bouton Formater (⌘↵) s'applique après une modification manuelle.
Votre pipeline mobile génère un client à partir de la spécification, et les avertissements ignorés deviennent des échecs en aval.
Validez la conformité au schéma
Collez-la dans validate-openapi. Corrigez d'abord les erreurs de Scalar : le lint n'aide pas sur une spécification invalide dans sa structure.
Passez le lint sur les opérations
Ouvrez lint-openapi. Résolvez les avertissements operation-operationId et operation-tags sur chaque endpoint public.
Formatez et ouvrez la PR
Passez la spécification corrigée dans format-openapi, avec le tri des clés si votre équipe veut des diffs stables. Relancez le lint avant le commit.
Un designer exporte du YAML minifié, et les relecteurs ne voient pas les renommages accidentels de chemins.
Formatez pour la lisibilité
Collez dans format-openapi, choisissez une indentation de 2 espaces et activez le tri des clés si l'équipe est d'accord.
Validez, puis passez le lint
Validez avec Scalar, puis lancez le lint pour paths-kebab-case et operation-success-response sur les nouveaux endpoints.
Documentez les réponses d'erreur
Le lint impose la présence d'une réponse 2xx. Ajoutez à la main des réponses 4xx et 5xx avec descriptions pour des contrats de production, car les erreurs du lint v1 ne les couvrent pas.
Relecture d'une PR, du design-first à la fusion
Traitez le trio du navigateur comme un contrôle rapide avant git push. La CI reste la source de vérité de l'équipe, mais détecter les problèmes en local économise des minutes de pipeline. Lancez validate-openapi pour corriger les erreurs de Scalar, puis format-openapi pour un diff lisible. Terminez par lint-openapi pour résoudre les erreurs puis les avertissements selon la politique de l'équipe, et faites le commit.
Au-delà d'un validate vert, demandez si les operationId sont uniques et stables pour le codegen. Demandez si les tags correspondent à la navigation du portail d'API et si chaque opération documente au moins une réponse de succès. Demandez aussi si les formes d'erreur courantes sont décrites pour les équipes clientes.
En CI, les équipes exécutent souvent Spectral, openapi-cli ou Redocly avec des rulesets plus stricts que ceux de FastMinify v1. Combinez le lint du navigateur avec notre guide CI/CD. Pour passer d'un schéma à l'autre, utilisez 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, consultez notre guide validation JSON Schema.
Conclusion
Des spécifications OpenAPI maintenables exigent plus que la validation du schéma. Le lint repère les lacunes d'operationId, de tags et de réponses qui bloquent les générateurs, et le formatage garde les PR faciles à relire. Validez d'abord, formatez pour les humains et lintez pour le style, le tout en local 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.
Lintez et formatez votre spécification OpenAPI maintenant
Articles connexes

Collez un token et un JWKS pour vérifier une signature RS256, ES256 ou HS256 dans le navigateur. Choix par kid, erreurs mesurées, claims à contrôler.

HTTP/2 et HTTP/3 changent le trajet des fichiers, pas leur poids. Mesures de taille, de compilation et de bundling : ce que la minification apporte encore.

Convertissez un epoch Unix en date lisible et inversement, distinguez secondes et millisecondes, et évitez les pièges de fuseau, de JWT et de changement d’heure.