L'audit, règle par règle.

#/audit analyse le schéma que la documentation a déjà chargé — dans le navigateur, rien n’est envoyé nulle part — et le note. Ce guide explique ce qui est vérifié, comment la note se calcule, et ce que le rapport transporte. La page de fonctionnalité est la vue d’ensemble.

L’ouvrir, et l’éteindre

L’audit s’adresse à l’auteur de l’API, pas à ses lecteurs : il n’a donc délibérément aucune entrée de nav. Son unique point d’entrée est un bloc en bas du tiroir de réglages, qui mène à #/audit — une vraie route, copiable, qu’on peut ouvrir directement. Rien n’est calculé tant que cette page n’est pas ouverte ; le rapport est ensuite gardé en mémoire, par spec.

features: { "audit": false } retire la route, le bloc de réglages et tout calcul — en multi-spec, par spec si vous voulez : une API notée, sa voisine non.

Ce que porte un constat

Chaque constat énonce une sévérité, un message, et sa justification — pourquoi ça compte et quoi faire, en une ou deux phrases. Trois sévérités :

Un constat sur une opération rendue pointe vers elle — vous lisez le constat, vous cliquez, vous regardez le problème. Un constat sur un callback pointe vers l’opération qui le déclare (un callback n’a pas de route à lui), et un constat sur une opération cachée montre un badge « caché » au lieu d’un lien mort : l’audit voit le schéma complet, mais ne lie jamais vers une vue sans route. Les constats d’ailleurs (components, info, …) affichent leur pointeur JSON.

La même omission répétée à travers un schéma est une décision, pas deux mille lignes : les constats sont repliés par règle, chaque ligne portant son compte, les occurrences se matérialisant cinquante par cinquante au dépliage.

Les cinq catégories

Exactitude — les contradictions internes du document, surtout des erreurs : un operationId dupliqué, un paramètre de chemin absent du template (ou l’inverse), un required listant des propriétés qui n’existent pas, un exemple ou un défaut que son propre schéma rejette, une exigence security nommant un scheme non déclaré, un component défini mais jamais référencé.

Documentation — ce que le document tait : opérations sans résumé ni description, paramètres et propriétés non décrits, opérations mutantes ne documentant aucune réponse d’erreur, info sans description, contact ou licence.

Obsolescence — l’inventaire de tout ce qui est deprecated: true, noté pour que le chiffre se lise comme la part de la surface encore actuelle, plus une vérification que la description de chaque élément déprécié nomme un remplacement ou une échéance.

Cohérence — les conventions du document, tenues contre lui-même : noms de paramètres et de propriétés hors de la convention dominante (détectée, pas imposée — les en-têtes sont exemptés, ils suivent la convention HTTP), styles de segments de chemin mélangés, le même schéma réécrit en ligne à plusieurs endroits au lieu d’être partagé.

Qualité documentaire — la catégorie qu’aucun linter généraliste ne peut avoir, parce qu’elle mesure comment le schéma se comporte dans ce moteur de rendu. Chaque message nomme la dégradation concrète : pas d’operationId, des liens profonds instables ; pas de servers, l’amorçage d’environnements n’a rien à proposer ; un flow OAuth2 sans ses URL, le bloc « Obtenir un jeton » ne peut pas tourner ; aucun exemple sur l’opération, les pré-remplissages retombent sur des échantillons générés ; des cycles plus profonds que le budget de dépliage, des murs « déplier » pour les lecteurs.

Conscience des versions

Les règles jugent le document contre la version qu’il déclare, dans les deux sens : une graphie qu’une version ultérieure a remplacée (nullable: true à partir de 3.1) et une construction employée en avance sur la version déclarée (webhooks ou tableaux de types dans un document 3.0, constructions 3.2 dans un 3.1) sont deux constats d’exactitude — tandis que le même nullable dans un document 3.0 passe, parce qu’il y est correct. Un document Swagger 2.0 converti reçoit en plus un constat par construction que la conversion n’a pu qu’approximer.

La notation

Chaque application de règle est une vérification réussie/échouée contre une cible — une opération, un paramètre, un component, le document. De là :

• Note de catégorie = taux de réussite pondéré sur ses vérifications applicables ; poids par sévérité : erreur 3, avertissement 2, info 1.
• Les vérifications non applicables ne comptent pas. Une API sans dépréciation fait 100 % en obsolescence, pas zéro ; une catégorie sans aucune vérification applicable est absente du rapport plutôt que notée.
• La lettre vient de la moyenne des notes de catégories : A ≥ 90, B ≥ 80, C ≥ 65, D ≥ 50, F en dessous.

L’en-tête du rapport montre la lettre et les barres de score par catégorie ; chaque titre de catégorie porte ses propres comptes par sévérité, pour peser une section sans remonter au sommaire.

Le rapport nomme ce qu’il a noté

Parce qu’un rapport se lit hors contexte — une capture collée, un onglet resté ouvert — la page énonce son identité et son périmètre : titre de l’API, info.version et version OpenAPI déclarée, contact et licence quand le document les porte, et le document en chiffres : opérations, groupes, webhooks, schemes de sécurité, schémas. Compté sur le document, opérations cachées comprises ; les zéros sont affichés, parce qu’« aucun scheme de sécurité » est une chose que le rapport s’apprête à noter.

L’export

« Copier le rapport en Markdown » emporte tout ce que la page montre — identité, chiffres, comptes par catégorie, chaque constat avec sa justification — plus un horodatage à la seconde : un rapport collé survit au schéma qu’il a noté, et sans date, le lecteur qui le retrouve dans un ticket ne peut pas dire s’il décrit encore quelque chose. Deux écarts assumés avec la page : les pointeurs JSON restent entiers (ils localisent le constat dans le fichier que vous allez éditer), et l’export voyage dans la langue où il a été lu. Collez-le dans une issue, corrigez, rechargez, ré-auditez — et quand le constat vit dans un schéma qui n’est pas à vous, les overlays sont le correctif qui n’exige pas de fork.