Notez le schéma, dans la page et en CI.

137 règles, sept catégories, une lettre.

L’exactitude au regard de la spécification OpenAPI, version par version. La sécurité, chaque règle rattachée à la RFC ou au risque OWASP qu’elle couvre. La documentation, l’obsolescence, la cohérence. Puis deux catégories qu’aucun linter générique n’a. La qualité documentaire, c’est ce qui va réellement se dégrader dans cette documentation rendue : un résumé manquant n’y est pas un point de style, c’est une ligne blanche dans votre navigation. La préparation aux agents, c’est ce qu’obtient un agent IA qui appelle votre API à travers un pont MCP ou une GPT Action.

Chaque catégorie obtient un score, le document une note de A à F, et chaque constat dit pourquoi il compte et comment le corriger. Dans la page, un constat pointe directement l’opération ou le schéma concerné : vous lisez, vous cliquez, vous regardez le problème. Un fichier trop abîmé pour être analysé a quand même son rapport, ses erreurs de syntaxe placées à leur ligne et leur colonne.

Rien n’est calculé tant que personne n’ouvre #/audit, et rien n’est envoyé nulle part : l’analyse porte sur le document que la page a déjà téléchargé. Comme elle s’adresse à l’auteur et non au lecteur, il n’y a pas d’entrée de navigation. L’accès se trouve en bas du tiroir des réglages.

{ "features": { "audit": false } }

Le même audit fait échouer le build.

apiglow audit fait tourner le même moteur en ligne de commande : la note que montre votre doc est celle qu’impose votre pipeline. La commande sort en erreur sur ce qu’elle trouve — un constat d’une sévérité donnée, une note ou un score sous votre seuil. Elle est livrée dans le paquet npm ; aucun jeu de règles à écrire, aucun service où s’inscrire.

Une API existante l’adopte sans d’abord solder son passé. Une baseline versionnée enregistre les constats d’aujourd’hui, et le job n’échoue que sur les nouveaux. Une entrée qui ne correspond plus à rien fait échouer le passage aussi : une baseline périmée ne masque jamais une régression.

Les constats arrivent là où les relecteurs regardent déjà. SARIF pour le code scanning de GitHub, des annotations sur le diff de la pull request, GitLab Code Quality dans le widget de merge request, du Markdown pour le résumé du job. Un rapport JSON versionné porte une empreinte stable par constat, avec la justification et le correctif de chaque règle — ce que lit un script ou un agent de code. Chaque constat est placé en fichier:ligne:colonne, y compris à travers des $ref vers d’autres fichiers. Le paquet livre une skill d’agent qui lance l’audit, corrige les constats et audite à nouveau — sans inventer ce que fait votre API.

Sur GitHub, apiglow/audit-action fait tout en une étape. La doc donne les recettes pour GitLab, pre-commit, oasdiff et les agents.

npx apiglow@0.3.0 audit openapi.yaml \
  --baseline audit-baseline.json --min-grade B \
  --format github --report sarif=audit.sarif

Vos exceptions, écrites noir sur blanc.

Une vraie API a des exceptions voulues. Le bloc audit de la configuration éteint une règle ou change sa sévérité, pour tout le document ou sous certains chemins seulement — une ancienne API figée, un champ public à dessein. La page et la ligne de commande lisent le même bloc : les deux notes concordent.

Une note calculée ainsi le dit : elle porte la mention Règles personnalisées à côté de la lettre, dans les deux exports et dans le JSON. Elle ne passe jamais pour la note par défaut.

{ "audit": {
    "rules": { "property-described": "off" },
    "overrides": [{ "paths": ["/paths/~1legacy~1*"],
                    "rules": { "response-example": "off" },
                    "reason": "frozen legacy API" }]
} }

Corriger un schéma qui n’est pas le vôtre.

Un document OpenAPI Overlay 1.1 est appliqué à la source analysée au chargement, avant la conversion Swagger 2.0 — une description fausse, un exemple manquant ou un mauvais tag sont donc corrigés dans la doc sans toucher au fichier en amont ni rien exécuter au préalable.

Les lecteurs ont aussi le leur. Un lecteur peut corriger le schéma depuis l’intérieur de la documentation, puis télécharger le correctif sous forme de fichier Overlay standard — la correction, dans un format que le propriétaire de l’API applique tel quel. « Votre doc est fausse » cesse d’être un rapport de bug pour devenir une pull request.

Des endpoints peuvent être masqués depuis le schéma ou depuis la configuration. C’est du masquage documentaire, pas du contrôle d’accès : une opération masquée est absente de la doc rendue, et toujours bien présente sur votre API.

Chaque lecteur a son propre journal.

La documentation garde l’empreinte des opérations que chaque lecteur a vues en dernier — dans son propre navigateur — et compare le schéma chargé à cette empreinte. Une fenêtre liste ce qui a été ajouté, retiré et modifié depuis ; des badges le signalent dans la navigation et dans le document, avec des noms accessibles, jamais par la couleur seule.

Il n’y a ni service de changelog ni compte. La comparaison porte sur sa dernière visite, pas sur une date de publication que vous devriez tenir à jour : la liste est vraiment la sienne.

Les formats qu’il lit vraiment.

OpenAPI 3.0, 3.1 et 3.2 sont rendus nativement, y compris la méthode query et $self de 3.2. Swagger 2.0 est converti au chargement, sans rien à exécuter avant. Les mots-clés JSON Schema 2020-12 sont rendus plutôt que silencieusement ignorés, et les références circulaires sont gérées — dans le document comme dans les exemples générés.

Webhooks et callbacks sont rendus comme des opérations, avec un simulateur capable de les déclencher, y compris en mode no-cors sans attente de réponse.