Deux ingénieurs de la même équipe livrent deux points d'API la même semaine. L'un renvoie created_at, l'autre renvoie createdAt. L'un pagine avec ?page=2, l'autre avec ?offset=20. L'un place les erreurs dans un objet error de niveau supérieur, l'autre intègre une chaîne message. Les deux passent la revue de code, car les relecteurs lisent la logique, pas les conventions de nommage. Six mois plus tard, votre surface d'API semble avoir été écrite par cinq entreprises différentes, et chaque intégration client nécessite un cas particulier.
Un linter OpenAPI existe pour détecter ces écarts avant la livraison. Il lit votre document OpenAPI, l'exécute par rapport à un ensemble de règles (les opérations nécessitent des descriptions, les schémas nécessitent des exemples, les noms de propriétés suivent une convention de casse, chaque réponse déclare un type de média) et fait échouer la compilation lorsqu'une règle est enfreinte. C'est la même idée qu'ESLint pour JavaScript ou RuboCop pour Ruby, appliqué à votre contrat d'API au lieu de votre code d'application. Si vous avez déjà souhaité que la revue de conception d'API puisse être automatisée comme le formatage de code, c'est exactement ce qu'un linter fait.
Ce qu'un linter OpenAPI vérifie réellement
Un linter opère sur le fichier de spécification, et non sur un serveur en fonctionnement. Pointez-le vers openapi.yaml et il parcourra chaque chemin, opération, paramètre, schéma et réponse, en appliquant les règles une par une. Les règles se répartissent en quelques catégories.
Validité. Est-ce même un document OpenAPI valide ? Chaque $ref se résout-il ? Les mots-clés requis sont-ils présents ? Cela chevauche la validation de schéma simple, et la plupart des linters le font comme base avant toute autre chose.
Complétude. Chaque opération a-t-elle un operationId, un résumé et une description ? Chaque paramètre s'explique-t-il ? Chaque schéma contient-il un example ? Ce sont les règles qui rendent la documentation et les SDK générés réellement utilisables, et ce sont celles que les humains oublient le plus souvent.
Cohérence. C'est le véritable atout. Les noms de propriétés utilisent une convention de casse. Les segments de chemin sont des noms pluriels. Les réponses d'erreur partagent une même structure. Chaque réponse 2xx déclare application/json. Les codes de statut sont utilisés comme l'entend la spécification HTTP. Aucune de ces choses n'est un bug isolément ; ensemble, elles font la différence entre une API qui semble conçue et une API qui semble assemblée.
Style interne. Vos propres conventions. Peut-être que chaque point d'API doit être étiqueté. Peut-être que DELETE doit renvoyer 204. Peut-être que les champs internes seulement doivent être préfixés. Ce sont des règles que personne d'autre n'a, et la capacité de les écrire est ce qui distingue un linter avec lequel vous pouvez vivre de celui contre lequel vous vous battez.
Une règle a une gravité : erreur, avertissement, information ou indice. Les erreurs font échouer la compilation ; les avertissements apparaissent mais la laissent passer. Ce réglage de gravité est ce qui vous permet d'adopter le linting sur une API existante sans vous noyer sous 4 000 violations dès le premier jour. Commencez par tout mettre en avertissement, corrigez les pires, puis promouvez les règles en erreur au fur et à mesure. Pour le côté conceptuel de l'importance de ces règles et de la manière dont les équipes les appliquent à grande échelle, le contexte plus détaillé se trouve dans comment les grandes entreprises garantissent la cohérence de la conception d'API.
Les principales options de linter OpenAPI
Voici les outils à connaître, avec une évaluation honnête de la place de chacun.
Spectral
Spectral, de Stoplight, est le standard de fait. C'est une interface de ligne de commande (CLI) et une bibliothèque open-source qui effectue le linting d'OpenAPI 2.0 et 3.x (ainsi que d'AsyncAPI, et de tout JSON ou YAML via JSONPath). Il est livré avec un ensemble de règles spectral:oas intégré qui couvre les règles de bon sens, et sa véritable force réside dans les règles personnalisées : vous décrivez ce qu'il faut vérifier en utilisant des sélecteurs given de style JSONPath, plus une fonction then, le tout dans un fichier YAML. Il existe un vaste catalogue de fonctions intégrées (truthy, pattern, casing, length, enumeration) et vous pouvez utiliser JavaScript lorsque vous avez besoin d'une logique que le format déclaratif ne peut pas exprimer.
Points forts : il est partout, il possède le plus grand écosystème de règles, des extensions d'éditeur existent pour VS Code et d'autres, et il fonctionne partout où Node fonctionne. Si vous voulez un outil reconnu par toute l'industrie, c'est celui-ci. Le compromis est que l'écriture de règles non triviales implique d'apprendre JSONPath et, à terme, l'API de fonction de Spectral. Nous avons un guide complet à ce sujet dans la création de règles Spectral personnalisées avec TypeScript si vous souhaitez approfondir la création.
Un .spectral.yaml minimal :
extends: ["spectral:oas"]
rules:
operation-operationId: error
operation-description: warn
property-casing:
description: Les propriétés doivent être en camelCase
given: $.components.schemas..properties[*]~
severity: error
then:
function: casing
functionOptions:
type: camel
Exécutez-le :
npx @stoplight/spectral-cli lint openapi.yaml
Redocly CLI
L'interface de ligne de commande (CLI) de Redocly regroupe le linting avec le bundling et la prévisualisation de la documentation. Son linter lit une configuration redocly.yaml, fournit un ensemble de règles intégrées et prend en charge des ensembles de règles configurables ainsi que des plugins personnalisés écrits en JavaScript. Les équipes utilisant déjà Redocly pour la documentation obtiennent le linting dans la même chaîne d d'outils sans ajouter de dépendance, et les règles intégrées sont orientées vers ce qui rend la documentation bien rendue.
Points forts : intégration étroite avec un flux de travail de documentation et de bundling, des valeurs par défaut décentes et un format de configuration qui s'intègre naturellement si vous évoluez dans l'écosystème Redocly. Si ce n'est pas déjà le cas, la bibliothèque de règles est plus petite que celle de Spectral et l'histoire des règles personnalisées est moins largement documentée.
npx @redocly/cli lint openapi.yaml
Vacuum
Vacuum est un linter plus récent écrit en Go, conçu pour la vitesse. Il est compatible avec les ensembles de règles Spectral, vous pouvez donc le pointer vers un fichier .spectral.yaml existant et obtenir les mêmes vérifications exécutées beaucoup plus rapidement sur de grandes spécifications. Pour un monorépertoire avec des dizaines de grands documents d'API, la différence de temps d'exécution est réelle.
Points forts : rapide, compatible avec les ensembles de règles Spectral, binaire unique sans environnement d'exécution Node. Si votre spécification est petite, le gain de vitesse est invisible, et l'écosystème et les outils d'éditeur sont plus jeunes que ceux de Spectral, il est donc plus attrayant comme accélérateur de CI plutôt qu'un choix à partir de zéro.
Swagger et openapi-spec-validator
Il est important de les nommer pour ne pas les confondre avec des linters. Le Swagger Editor et swagger-cli/openapi-spec-validator vérifient si un document est un OpenAPI valide. Il ne s'agit que de validité, pas de cohérence ou de style interne. Ils accepteront volontiers une spécification où chaque propriété est nommée différemment, car rien dans la spécification OpenAPI ne l'interdit. La validation est nécessaire, mais c'est le minimum, pas le summum. Si vous choisissez entre les outils de la famille Swagger et une plateforme de conception complète, les compromis sont expliqués dans les alternatives à Swagger qui testent également votre API.
Vérifications au moment de la conception dans Apidog
Les outils ci-dessus s'exécutent après que vous ayez un fichier. L'autre endroit pour détecter les incohérences est avant que le fichier n'existe, pendant que vous concevez le point d'API. Apidog est une plateforme axée sur la conception : vous construisez des points d'API et des schémas de données dans un éditeur visuel, et cela maintient votre projet cohérent en interne au fur et à mesure. Les schémas de données réutilisables signifient que le même modèle est référencé partout au lieu d'être redéfini par point d'API, ce qui élimine toute une classe d'écarts de nommage à la source. Les composants de réponse partagés font de même pour les structures d'erreur.
Apidog n'est pas un remplacement direct d'un ensemble de règles Spectral ; si vous avez des règles .spectral.yaml validées, continuez à les exécuter. Ce qu'Apidog change, c'est la quantité de problèmes que votre linter trouve en premier lieu. Lorsque la surface de conception impose la réutilisation, le linter passe d'un mur de violations à une détection occasionnelle. Et parce qu'Apidog importe et exporte le standard OpenAPI 3.x, le fichier que vous donnez à Spectral ou Vacuum en CI est le même artefact, de sorte que les deux couches s'empilent au lieu de se concurrencer.
Une configuration de linter que vous pouvez exécuter dès aujourd'hui
Une bonne configuration exécute la vérification à trois endroits, chacun avec un rôle différent. L'éditeur fournit un feedback instantané. Le hook de pré-commit arrête les erreurs évidentes localement. La CI est la barrière que personne ne peut contourner. Voici chaque couche.
Couche 1 : l'éditeur
Installez l'extension Spectral pour VS Code et ajoutez un fichier .spectral.yaml à la racine de votre dépôt. L'extension le détecte automatiquement et souligne les violations au fur et à mesure que vous modifiez la spécification, de la même manière qu'une faute de frappe est soulignée en rouge. C'est la boucle de feedback la moins chère possible, car le développeur corrige le problème avant même qu'il ne devienne un commit. Rien d'autre à configurer ; le fichier dans le dépôt est la seule source de vérité pour les règles.
Couche 2 : pré-commit
Ajoutez un hook pour qu'une spécification défectueuse n'atteigne jamais le dépôt distant. L'utilisation d'un script package.json plus un hook Git est suffisante :
{
"scripts": {
"lint:api": "spectral lint openapi.yaml --fail-severity=error"
}
}
# .git/hooks/pre-commit (ou via husky)
#!/bin/sh
npm run lint:api || {
echo "Le lint OpenAPI a échoué. Corrigez la spécification avant de commiter."
exit 1
}
Le drapeau --fail-severity=error est la partie importante. Il indique au linter de ne quitter qu'avec un code d'erreur (non-zéro) en cas d'erreurs, de sorte que les avertissements s'affichent toujours sans bloquer le commit. Cela maintient le hook utilisable pendant que vous promouvez encore les règles.
Couche 3 : CI
C'est la barrière qui compte, car c'est celle qu'un coéquipier ne peut pas contourner avec --no-verify. Une étape GitHub Actions :
name: API lint
on: [pull_request]
jobs:
spectral:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: actions/setup-node@v4
with:
node-version: 20
- run: npx @stoplight/spectral-cli lint openapi.yaml --fail-severity=error
Le job échoue lorsque la spécification enfreint une règle de niveau erreur, la demande de tirage (pull request) affiche une croix rouge, et la fusion est bloquée jusqu'à ce que quelqu'un la corrige. C'est tout le mécanisme d'application. Pas de tableaux de bord, pas de harcèlement ; la règle est soit respectée, soit elle ne l'est pas.
Couche 4 : tester l'API décrite par la spécification
Un linter prouve que la spécification est bien formée et cohérente. Il ne dit rien sur la correspondance entre l'API en cours d'exécution et la spécification. Cet écart est l'endroit où se cache la dérive de contrat : un document magnifiquement "linté" décrivant un comportement que le serveur a cessé d'honorer il y a trois versions. Pour combler cet écart, vous exécutez des tests sur l'API en direct dans le même pipeline.
C'est ici que l'interface de ligne de commande (CLI) Apidog s'intègre aux côtés de votre linter. C'est un paquet npm, apidog-cli, et il exécute vos scénarios de test Apidog depuis la ligne de commande afin qu'ils s'insèrent dans la CI juste après l'étape de linting :
npm install -g apidog-cli
apidog run --access-token $APIDOG_ACCESS_TOKEN -t 605067 -e 1629989 -r cli,junit
La commande apidog run quitte avec un code d'erreur (non-zéro) lorsqu'un test échoue, le même contrat sur lequel chaque étape de CI s'appuie, de sorte qu'un test échoué bloque la fusion exactement de la même manière qu'un linting échoué. Le rapporteur -r junit émet du XML que votre tableau de bord CI analyse en un arbre de succès/échec, et -e pointe les mêmes scénarios vers des environnements de staging ou de production sans les dupliquer. La CLI peut également importer un document OpenAPI 3.x, de sorte que le fichier que votre linter vérifie est le même fichier qu'Apidog utilise pour les tests. Pour le modèle de pipeline complet, y compris les rapporteurs et la gestion des codes de sortie, consultez le guide sur l'exécution de la CLI Apidog dans votre pipeline CI/CD. Si vous êtes spécifiquement sur GitHub, la CLI Apidog dans GitHub Actions propose un flux de travail à copier-coller.
Lint en premier, test en second. L'étape de lint est rapide et détecte les problèmes de conception ; l'étape de test est plus lente et détecte les problèmes de comportement. Exécutez-les en deux étapes et une demande de tirage (pull request) doit valider les deux.
Choisir et adopter un ensemble de règles sans douleur
Choisir l'outil est la partie facile. L'adopter sur une API qui existe déjà est là où les équipes stagnent, car la première exécution sur une spécification mature renvoie des centaines de violations et la réaction évidente est de tout désactiver.
Ne partez pas de zéro règles et ne commencez pas avec toutes les règles en erreur. Commencez par l'ensemble de règles intégré (spectral:oas) avec tout ce que vous ajoutez défini en warn (avertissement). Exécutez-le, lisez le décompte et corrigez d'abord les erreurs de validité, car ce sont de vrais bugs. Ensuite, choisissez les deux ou trois règles de cohérence qui importent le plus pour vos clients (généralement la casse des propriétés et une structure d'erreur unique) et ne promouvez que celles-ci en error (erreur). Tout le reste reste un avertissement. À chaque sprint, promouvez un ou deux avertissements supplémentaires en erreurs à mesure que le codebase se met à jour. En un trimestre, l'ensemble des règles est appliqué et personne n'a eu à arrêter les livraisons pour y arriver.
Écrivez les règles de style interne avec parcimonie. Chaque règle personnalisée est un code que quelqu'un doit maintenir et expliquer à la prochaine recrue. Une règle ne gagne sa place que lorsqu'une violation vous a réellement porté préjudice, pas parce qu'elle pourrait le faire. Pour les règles que vous écrivez, appuyez-vous sur la couche de conception pour les rendre rares : si vos schémas sont réutilisés à partir d'une définition centrale, une règle de casse des propriétés ne se déclenche presque jamais car il n'y a qu'un seul endroit où le nom est défini. Le cadre conceptuel pour savoir quelles règles méritent d'être appliquées, par rapport à celles qui sont du "bikeshedding", est couvert dans les meilleures pratiques de conception d'API.
Si vous concevez dans un langage différent du YAML brut, le linter s'applique toujours. TypeSpec se compile en OpenAPI, et vous effectuez le linting du document émis de la même manière ; le linter ne se soucie pas de la façon dont le fichier a été rédigé, seulement de ce qu'il dit.
Où le linter s'inscrit dans la boucle de conception plus large
Un linter est un contrôle dans un flux de travail axé sur la conception, pas la totalité. La boucle complète est la suivante : concevoir le contrat, le linter, le simuler (mock) pour que les clients puissent s'y baser, tester l'implémentation par rapport à celui-ci, et en publier la documentation. Sautez une étape et les autres perdent de leur valeur. Une spécification lintée que personne ne simule bloque toujours le travail frontal. Une spécification simulée que personne ne teste s'éloigne toujours de la réalité.
La raison de placer la conception en premier dans cette boucle est la même que celle pour laquelle le linting fonctionne : détecter les problèmes là où ils sont les moins chers à corriger. Changer un nom de propriété dans l'outil de conception est une seule modification. Le changer après que trois équipes aient livré en se basant sur l'ancien nom est une migration. Le linter impose la cohérence sur le fichier ; un processus axé sur la conception l'impose sur la décision avant que le fichier n'existe. Si vous souhaitez l'argument plus large pour le séquençage, API-first vs API design-first vs code-first expose les compromis, et les outils de conception d'API contract-first couvrent l'outillage qui le supporte.
Apidog couvre toute cette boucle en un seul endroit : concevez avec des schémas réutilisables, simulez instantanément, testez avec la CLI en CI, et exportez un OpenAPI propre pour le linter sur lequel vous vous standardisez. Le linter a toujours un rôle ; il y a juste moins de choses à y déceler.