Linting OpenAPI avec Spectral : Une approche simplifiée

Deux ingénieurs de la même équipe livrent deux points de terminaison la même semaine. L'un renvoie created_at, l'autre createdAt. L'un pagine avec ?page=, l'autre avec ?offset=. Aucun n'est incorrect en soi. Ensemble, ils donnent l'impression que votre API a été assemblée par des inconnus, et chaque client qui la consomme en paie le prix. Le fichier OpenAPI se valide correctement. Il est analysé, il s'affiche dans Swagger UI, il génère un SDK. Il est juste incohérent, et un simple validateur n'a rien à dire à ce sujet.

C'est précisément cette lacune qu'un linter comble. Un validateur répond « cette spécification est-elle conforme à OpenAPI ? » Un linter répond « cette spécification suit-elle les règles sur lesquelles nous nous sommes mis d'accord ? » L'outil open source le plus populaire pour la seconde question est Spectral, le linter de Stoplight pour les documents JSON et YAML. Il est livré avec un ensemble de règles OpenAPI intégré, vous permet d'écrire vos propres règles et s'exécute depuis le terminal ou votre éditeur. Si vous souhaitez un moyen gratuit et scriptable d'appliquer un guide de style API, Spectral est le premier arrêt évident, et ce guide vous montre comment l'utiliser correctement.

Il montre également le compromis. Spectral est un ensemble de règles que vous assemblez et maintenez. Pour les équipes qui préfèrent obtenir des vérifications de cohérence, des serveurs de maquette et des tests exécutables à partir d'un seul endroit sans écrire manuellement des règles YAML, Apidog intègre ce travail directement dans l'interface de conception. Nous allons d'abord attribuer le mérite à Spectral, puis montrer où la voie tout-en-un vous épargne la maintenance.

Ce que Spectral fait réellement

Spectral est un linter générique. Vous le dirigez vers un document structuré, lui donnez un ensemble de règles, et il signale chaque endroit où le document enfreint une règle, avec un numéro de ligne et une gravité. Il n'est pas spécifique à OpenAPI ; il comprend OpenAPI, AsyncAPI et Arazzo d'emblée, et vous pouvez linter n'importe quel fichier JSON ou YAML avec des règles personnalisées.

La raison pour laquelle il est important pour le travail API est son ensemble de règles intégré spectral:oas. Cet ensemble de règles encode une longue liste de conventions OpenAPI : les opérations devraient avoir un operationId, l'objet info devrait contenir une description et un contact, les balises devraient être définies avant d'être utilisées, les paramètres ne devraient pas se dupliquer. Exécutez-le contre une spécification réelle et vous obtiendrez presque toujours une liste d'avertissements dès le premier essai. Aucun d'entre eux ne bloque un analyseur. Tous rendent la spécification plus difficile à gérer.

C'est un travail différent de la validation structurelle. Un outil comme swagger-cli ou Redocly répond à la question de savoir si le document est conforme au schéma OpenAPI. Spectral répond à la question de savoir si le document suit votre style interne en plus de cela. Vous voulez les deux, et les deux vérifications s'intègrent proprement dans un pipeline. Nous examinons la partie validation dans le guide sur la validation des spécifications OpenAPI ; cet article porte sur la partie style et cohérence.

Installer Spectral et exécuter votre premier lint

Spectral est livré sous forme de paquet npm. L'interface de ligne de commande est @stoplight/spectral-cli. Installez-la globalement :

npm install -g @stoplight/spectral-cli

Node.js est la seule dépendance système, donc toute machine ou image CI avec Node déjà installé peut l'exécuter. Si vous préférez ne pas l'installer globalement, npx @stoplight/spectral-cli ... fonctionne sur les exécuteurs de build éphémères.

Spectral a besoin d'un ensemble de règles pour savoir quoi vérifier. La convention est un fichier nommé .spectral.yaml dans votre répertoire de travail. Le plus petit ensemble utile étend les règles OpenAPI intégrées :

# .spectral.yaml
extends: ["spectral:oas"]

Maintenant, lintez une spécification. Avec un fichier .spectral.yaml dans le répertoire actuel, Spectral le détecte automatiquement :

spectral lint openapi.yaml

Ou pointez explicitement vers un ensemble de règles :

spectral lint openapi.yaml --ruleset .spectral.yaml

La sortie est lisible à dessein. Chaque constatation indique la ligne et la colonne, la gravité, la règle qui a été déclenchée et un message compréhensible :

openapi.yaml
  3:6   warning  info-contact      Info object should contain `contact` object.
  5:10  error    info-description   OpenAPI object info `description` must be present.

✖ 2 problems (1 error, 1 warning, 0 infos, 0 hints)

Cette première exécution sur une spécification existante est le moment où la plupart des équipes réalisent à quel point des incohérences se sont immiscées. Les règles n'ont jamais été appliquées, donc personne ne les a suivies.

Écrire vos propres règles

L'ensemble de règles intégré est un point de départ, pas la destination. La vraie valeur de Spectral est d'encoder les conventions de votre équipe sous forme de règles qu'une machine vérifie à chaque changement. Une règle a quatre éléments : ce qu'il faut regarder (given, une expression JSONPath), ce qu'il faut vérifier (then, une fonction), la gravité à donner (severity), et ce qu'il faut dire en cas d'échec (message).

Voici une règle qui impose les chemins en kebab-case, une convention interne courante :

# .spectral.yaml
extends: ["spectral:oas"]
rules:
  paths-kebab-case:
    description: Paths should be kebab-case.
    message: "{{property}} should be kebab-case (lower-case, hyphen-separated)"
    severity: warn
    given: $.paths[*]~
    then:
      function: pattern
      functionOptions:
        match: "^(\\/|[a-z0-9-.]+|{[a-zA-Z0-9_]+})+$"

Le given sélectionne chaque clé de chemin. Le then exécute la fonction intégrée pattern contre une expression régulière. Tout ce qui ne correspond pas au modèle est signalé comme un avertissement avec votre message. Vous pouvez interdire les ID entiers au profit des UUID, exiger une réponse d'erreur sur chaque POST, interdire les numéros de version dans les URL de serveur, ou exiger que chaque opération porte une description. Spectral propose plusieurs fonctions de base (truthy, pattern, schema, length, enumeration, et plus encore) de sorte que la plupart des conventions ne nécessitent aucun code.

Lorsqu'une règle nécessite une logique qu'une option de fonction ne peut pas exprimer, Spectral vous permet d'écrire des règles en JavaScript ou TypeScript et d'importer des fonctions personnalisées. C'est là que l'outil devient puissant et que la maintenance commence. Si vous voulez approfondir, nous avons un guide complet sur la création de règles Spectral personnalisées avec TypeScript.

Gravité, et faire échouer la compilation

Chaque règle Spectral a une gravité : error, warn, info ou hint. Par défaut, l'interface de ligne de commande ne se termine avec un code non nul que lorsqu'elle trouve une error. Les avertissements sont affichés mais ne font pas échouer l'exécution. C'est acceptable lorsque vous nettoyez une spécification héritée et que vous ne voulez pas que mille avertissements bloquent chaque fusion.

Une fois votre spécification propre, resserrez la barrière. L'option --fail-severity contrôle le seuil :

spectral lint openapi.yaml --fail-severity=warn

Désormais, un avertissement renvoie également le code de sortie 1, ce qu'une étape de CI lit pour se marquer comme échouée. C'est le mécanisme qui transforme un linter en une véritable porte de qualité : le pipeline bloque la fusion dès que la spécification s'écarte du guide de style. Vous pouvez également remplacer les gravités de règles individuelles dans votre ensemble de règles, faisant passer une règle qui vous intéresse de warn à error ou désactivant une règle qui ne convient pas à votre équipe en la définissant sur off.

Exécuter Spectral en CI

Un linter qui ne s'exécute que lorsque quelqu'un s'en souvient n'est pas une porte. Le but est de l'exécuter à chaque push, sur une machine propre, avec le même ensemble de règles pour tout le monde. Spectral rend cela rapide. Voici un job GitHub Actions qui linte la spécification sur toute pull request qui la modifie :

name: Lint OpenAPI

on:
  pull_request:
    paths:
      - "openapi.yaml"

jobs:
  spectral:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: "20"
      - run: npm install -g @stoplight/spectral-cli
      - run: spectral lint openapi.yaml --fail-severity=warn

Pour des rapports plus riches, Spectral peut émettre du XML JUnit, que la plupart des tableaux de bord CI analysent en un arbre de réussite/échec :

spectral lint openapi.yaml -f junit -o results.xml

Connectez cet artefact à votre tableau de bord et chaque contributeur verra quelle règle a échoué et où, sans avoir à lire les journaux bruts. Si vous voulez une vue plus large de l'intégration des contrôles structurels, du linting et de la détection des changements de rupture, les modèles OpenAPI-en-CI généralisent au-delà de tout outil unique. Traiter la spécification comme du code est l'état d'esprit qui rend tout cela efficace.

Où Spectral vous demande beaucoup

Spectral est bon dans ce qu'il fait. Le revers de la médaille est qu'il ne fait qu'une chose, et le reste du cycle de vie de la spécification est à votre charge pour être assemblé. Quelques réalités apparaissent une fois qu'une équipe l'adopte au-delà de la démonstration.

Vous possédez l'ensemble de règles. Les règles intégrées spectral:oas sont génériques. Votre véritable guide de style se trouve dans les règles personnalisées que vous écrivez, examinez, versionnez et maintenez à jour à mesure que les conventions évoluent. Cet ensemble de règles devient une petite base de code avec son propre fardeau de maintenance, et JSONPath ainsi que les fonctions personnalisées sont une compétence que tout le monde n'a pas dans l'équipe.

Il linte le document, pas l'API. Spectral lit le fichier. Il ne peut pas vous dire si le service en cours d'exécution renvoie réellement ce que la spécification promet. Une spécification peut passer toutes les règles de lint et décrire toujours un point de terminaison dont l'implémentation s'est éloignée il y a des mois. Combler cette lacune signifie envoyer de vraies requêtes et faire des assertions sur les réponses, ce qui est un outil entièrement différent.

C'est une pièce d'une chaîne plus longue. Après le linting, vous avez toujours besoin de mocks pour les équipes frontend, d'un site de documentation et d'une suite de tests automatisés. Chacun est un outil séparé à installer, configurer et maintenir synchronisé avec la spécification. Le linter ne connaît aucun d'entre eux, de sorte que la spécification est ré-analysée et réinterprétée à chaque étape.

Rien de tout cela n'est une critique de Spectral. C'est un linter ciblé et il est honnête quant à son champ d'application. Mais « ciblé » signifie que le travail d'intégration vous incombe.

La voie la plus simple : la cohérence intégrée à l'interface de conception

Voici l'autre chemin. Au lieu de traiter la cohérence comme une étape de linting ajoutée après la rédaction de la spécification, Apidog la traite comme faisant partie de la rédaction de la spécification.

Apidog est une plateforme API tout-en-un : vous concevez le schéma, déboguez les requêtes, construisez des scénarios de test, simulez des points de terminaison et publiez de la documentation dans un seul espace de travail. Parce que la conception se déroule à l'intérieur de l'outil, les vérifications de cohérence se produisent au fur et à mesure que vous tapez. Le concepteur visuel signale les problèmes structurels dès qu'ils apparaissent, de la même manière qu'un compilateur souligne une erreur de syntaxe, afin que vous les corrigiez avant qu'ils n'atteignent un commit. Vous n'exécutez pas un linter séparé après coup ; l'éditeur est le linter.

La plus grande différence se situe en aval. Le même contrat que vous concevez devient votre serveur de maquette, votre documentation interactive et vos scénarios de test, sans ré-analyse et sans deuxième outil à maintenir synchronisé. Lorsque vous voulez ces vérifications dans un pipeline, l'Apidog CLI exécute vos scénarios de test en mode headless depuis le terminal et se termine avec un code non nul en cas d'échec, exactement le comportement de porte que vous attendiez d'un linter, sauf qu'il teste l'API en cours d'exécution par rapport au contrat au lieu de seulement lire le fichier. Installez-le avec une seule commande npm et pointez-le vers un scénario :

npm install -g apidog-cli
apidog run --access-token $APIDOG_ACCESS_TOKEN -t <scenarioId> -e <environmentId> -r cli

Cela comble le vide laissé par Spectral. Spectral confirme que le document suit votre style. L'Apidog CLI confirme que l'implémentation correspond toujours au document. Pour la référence complète des options, exécutez apidog run --help ou lisez le guide complet de l'interface de ligne de commande.

Le compromis est donc réel et mérite d'être clairement énoncé. Spectral vous offre un linter gratuit, scriptable et indépendant du fournisseur que vous assemblez et maintenez. Apidog vous offre la cohérence, la simulation, la documentation et des tests exécutables à partir d'une seule source de vérité, avec beaucoup moins de choses à assembler. Si une étape de linting portable dans une chaîne d'outils existante est tout ce dont vous avez besoin, Spectral est une excellente réponse. Si vous voulez que l'ensemble du cycle de vie tienne sans devenir un projet d'outillage à part entière, le chemin intégré vous coûtera moins cher sur le long terme.

Spectral vs Apidog en un coup d'œil

Utilisez ce tableau comme aide à la décision, pas comme un tableau de score. Le bon choix est celui qui correspond à la part du cycle de vie que vous souhaitez confier à un seul outil.

Questions fréquemment posées

Spectral est-il gratuit ? Oui. Spectral est open source sous la licence Apache 2.0, maintenu par Stoplight. L'interface de ligne de commande, l'ensemble de règles OpenAPI intégré et la création de règles personnalisées sont tous gratuits.

Spectral valide-t-il la conformité de ma spécification à OpenAPI ? En partie. Les règles intégrées détectent de nombreux problèmes structurels, mais Spectral est un linter, pas un validateur de schéma dédié. Associez-le à un validateur pour une couverture structurelle complète. Le guide sur la validation des spécifications OpenAPI couvre cet aspect, et les meilleurs outils de validation OpenAPI comparent les options.

Spectral peut-il tester mon API en cours d'exécution ? Non. Spectral ne lit que le fichier de spécification. Pour vérifier que l'API en direct correspond au contrat, vous avez besoin d'un exécuteur qui envoie de vraies requêtes et effectue des assertions sur les réponses, comme l'Apidog CLI.

Comment faire en sorte qu'un avertissement Spectral fasse échouer ma compilation CI ? Exécutez spectral lint openapi.yaml --fail-severity=warn. Par défaut, seule la gravité error fait échouer la compilation ; --fail-severity=warn fait également en sorte que les avertissements renvoient un code de sortie non nul.

Quelle est la différence entre Spectral et Apidog ? Spectral est un linter open source ciblé que vous configurez et maintenez. Apidog est une plateforme tout-en-un où la conception, les vérifications de cohérence, la simulation, la documentation et les tests coexistent, ce qui réduit l'assemblage et la synchronisation. Voir Apidog vs Swagger pour une comparaison connexe du paysage des outils de conception.

En résumé

Spectral résout un problème réel que les validateurs simples ignorent : maintenir une spécification OpenAPI cohérente avec les conventions sur lesquelles votre équipe s'est mise d'accord. Installez @stoplight/spectral-cli, étendez spectral:oas, ajoutez quelques règles personnalisées et protégez votre pipeline avec --fail-severity=warn. Pour de nombreuses équipes, c'est suffisant et cela ne coûte rien.

Le coût apparaît plus tard, dans les règles que vous maintenez et le reste du cycle de vie que vous assemblez autour du linter. Si vous préférez obtenir la cohérence, les mocks, la documentation et les tests exécutables à partir d'une seule source de vérité, téléchargez Apidog et construisez votre spécification là où les vérifications font déjà partie de l'interface. Dans tous les cas, l'objectif est le même : une spécification à laquelle toute votre équipe peut faire confiance, appliquée par une machine plutôt que par un espoir.