OpenAPI : linter, formater et structurer une API maintenable

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.

09.08.2026
8 min de lecture
Partager cet article:
openapilintformatapi-designRESTTutoriel

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.

Détection des operationId, tags et réponses 2xx manquants avant génération SDK ou portail
Sous-ensemble Spectral : info-contact, paths-kebab-case, operation-description, et plus
Formatage de JSON ou YAML pour des diffs de PR stables, avec tri récursif des clés en option
100 % local : les spécifications ne quittent pas le navigateur, ce qui convient aux contrats internes
Chaîne conseillée : valider → formater → linter → commit

Limites honnêtes et conception d'API maintenable

Ce que lint-openapi ne fait pas

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.

Pas de test de sécurité (flux d'authentification, application des scopes)
Pas de test de contrat à l'exécution sur des endpoints réels
Pas de regroupement automatique de plusieurs fichiers : collez une spécification autonome à chaque exécution
Pas de prise en charge de Swagger 2.0 : OpenAPI 3.x uniquement
Les avertissements ne bloquent pas un résultat « Valide avec avertissements » : traitez-les comme des bloqueurs de fusion si la politique de l'équipe le demande
operationId, tags et réponses d'erreur

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éciation
tags : regroupement par domaine fonctionnel, aligné sur les sections du portail développeur
Réponses 2xx : le lint impose leur présence, donc ajoutez des réponses 400, 401, 404 et 500 explicites avec schémas là où les clients en ont besoin
info.description et info.contact : le lint avertit s'ils sont absents, remplissez-les pour les API externes
Nommage des chemins : préférez /pet-orders à /petOrders, car la règle kebab-case s'aligne sur les conventions REST
Quand passer aux outils de CI

Les outils du navigateur accélèrent le retour, et les pipelines imposent la politique de l'organisation.

Rulesets Spectral personnalisés (nommage, en-têtes de sécurité, pagination)
Détection de changements cassants entre versions de spécification
Regroupement de spécifications en plusieurs fichiers avec résolution des $ref externes
Validation d'import propre à chaque passerelle (AWS API Gateway, plugins Kong)
Documentez la version OpenAPI visée (3.0 ou 3.1, soit le draft de JSON Schema) dans le README du dépôt

Valider, formater puis linter, dans l'ordre design-first

Trois outils, trois intentions

Ne permutez pas les étapes pendant la relecture : chaque outil répond à une question différente sur votre fichier OpenAPI.

Validate (validate-openapi) : conformité au schéma OpenAPI 3.x via Scalar, avec un verdict valide ou invalide
Format (format-openapi) : indentation et lisibilité, sans corriger les écarts sémantiques ou de style
Lint (lint-openapi) : règles de type Spectral sur les opérations des chemins, avec avertissements et erreurs distincts de la validation du schéma
Ordre conseillé : valider → formater → linter avant la fusion
La syntaxe JSON seule ne suffit pas : voir le guide de validation pour la différence entre schéma et lint
Règles de lint en v1 (sous-ensemble Spectral)

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ègles
info-contact (avertissement) : info.contact devrait être présent
info-description (avertissement) : info.description non vide
paths-kebab-case (avertissement) : segments de chemin en kebab-case ou vN
operation-operationId (avertissement) : chaque opération a un operationId non vide
operation-tags (avertissement) : au moins un tag par opération
operation-description (avertissement) : summary ou description requis
operation-success-response (erreur) : au moins une réponse 2xx, default seul ne suffit pas
path-item-ref (avertissement) : $ref d'un path item non développée en lint v1
Ce que le lint ne couvre pas (v1)

Un périmètre honnête : ne présumez pas d'une parité avec Spectral, Redocly ou les moteurs de politique des passerelles.

Opérations de chemins uniquement : webhooks et callbacks sont hors périmètre en v1
Pas d'envoi de ruleset personnalisé : le sous-ensemble est fixe, ce n'est pas un exécuteur Spectral
Le lint ne remplace pas la validation du schéma : utilisez validate-openapi pour la conformité Scalar
Aucune récupération des URL de $ref externes : collez une spécification autonome
Limite d'entrée de 512 KiB : les spécifications très volumineuses relèvent de la CI
Formater pour la revue, pas pour la sémantique

Le 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.

Du JSON en entrée donne du JSON en sortie, du YAML en entrée donne du YAML : le type d'entrée est conservé
Les commentaires YAML disparaissent au formatage : sauvegardez avant de reformater une spécification annotée
Un openapi: 3.0 numérique en YAML est normalisé en chaîne 3.0.0
Le tri des clés aide la relecture d'une PR, mais il ne réorganise pas les sections en tenant compte d'OpenAPI
Un OpenAPI invalide peut quand même être formaté si l'analyse réussit : validez de nouveau après des modifications importantes

Linter et formater OpenAPI pas à pas

Utiliser le linter OpenAPI

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.

Lint en direct dans l'éditeur Monaco après un court debounce
Liste des problèmes avec code de règle, niveau et chemin JSON Pointer
Panneau de résultats : nombre d'erreurs et d'avertissements, plus les statistiques de chemins et d'opérations
Les erreurs d'analyse affichent un numéro de ligne quand il est connu
Les documents Swagger 2.0 échouent à la règle not-openapi : migrez d'abord vers OpenAPI 3
Utiliser le formateur OpenAPI

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.

Indentation de 2 ou 4 espaces, selon la convention de l'équipe
Tri récursif des clés en option pour des diffs git stables
Panneau de sortie avec coloration Shiki
Enchaînez format → validate → lint pour un passage complet avant la fusion
Associez-le au validateur JSON si la syntaxe brute est douteuse
Génération de SDK bloquée par un operationId manquant

Votre pipeline mobile génère un client à partir de la spécification, et les avertissements ignorés deviennent des échecs en aval.

1

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.

2

Passez le lint sur les opérations

Ouvrez lint-openapi. Résolvez les avertissements operation-operationId et operation-tags sur chaque endpoint public.

3

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 diff YAML illisible pendant la relecture d'un contrat

Un designer exporte du YAML minifié, et les relecteurs ne voient pas les renommages accidentels de chemins.

1

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.

2

Validez, puis passez le lint

Validez avec Scalar, puis lancez le lint pour paths-kebab-case et operation-success-response sur les nouveaux endpoints.

3

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

Liste de contrôle conseillée avant 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.

Points d'attention du relecteur

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.

Compléter avec la CI et les outils voisins

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

Enchaînez valider → formater → linter avant chaque PR de spec
Traitez les avertissements du lint comme des bloqueurs de fusion si la génération de SDK est en jeu
Activez le tri des clés seulement si toute l'équipe est d'accord, car il change la sémantique des diffs
Relisez le guide validation quand des erreurs Scalar apparaissent avant de déboguer le lint
Passez à Spectral ou Redocly en CI pour les règles propres à l'organisation au-delà du sous-ensemble v1
Partager cet article
Partager cet article: