Toutes les clés, une page.

La config vit dans la page hôte, dans un bloc <script id="api-doc-config" type="application/json"> — ou dans la globale window.API_DOC_CONFIG quand vous voulez des commentaires autour. Seule openapi.url, spec ou specs est requise ; toutes les autres clés ont une valeur par défaut.

Les clés sont groupées ci-dessous comme dans la config elle-même. Les valeurs par défaut sont indiquées quand il en existe une, en date de la v0.3.0.

L’objet complet en un seul bloc copiable, un commentaire par clé, vit sur Référence complète — et le builder l’écrit pour vous, station par station.

openapi

openapi.url

URL du schéma OpenAPI 3.0.x–3.2.x, JSON ou YAML. Le serveur qui l’héberge doit autoriser la lecture cross-origin (CORS).

openapi.spec

Le schéma lui-même — objet JS ou chaîne JSON — porté par la page : aucune requête, aucun CORS. Gagne sur url.

openapi.specs

Plusieurs schémas dans une installation : des entrées [{ id, title, url }], presque toutes les clés surchargeables par entrée. Gagne sur url. Voir le guide multi-spec.

openapi.default

La spec affichée à l’arrivée en multi-spec (sinon la première entrée).

openapi.hide

Motifs retirant des opérations de la nav, de la recherche et des exports : "tag:Internal", "DELETE /admin/*", "/admin/*", "resetDatabase" (operationId — l’id de repli {method}-{slug} matche aussi). Du masquage documentaire, pas de la sécurité — le navigateur télécharge toujours le schéma complet. Voir Couverture OpenAPI & contrôle du schéma.

openapi.overlays

Documents OpenAPI Overlay 1.1 (URL ou objet inline) appliqués au schéma au chargement, dans l’ordre déclaré. Toute action en échec est signalée, jamais silencieuse. Sémantique complète dans le guide du schéma.

openapi.userOverlay

Un correctif de départ amorcé dans l’éditeur d’overlay du lecteur (null par défaut). Par spec, il remplace le document de la racine au lieu de s’empiler, et ré-amorcer avec un autre document jette les modifications locales du lecteur.

theme

theme.defaultpar défaut"system"

Thème appliqué au premier chargement ; le choix persistant du lecteur prime ensuite. "system" suit le prefers-color-scheme de l’OS dans la première paire clair/sombre d’available.

theme.availablepar défaut["apiglow", "apiglow-dark"]

Thèmes offerts dans le sélecteur — le défaut est la paire signature de l’app. Les 35 thèmes daisyUI standard sont dans le bundle : en lister un ne coûte rien.

theme.custom

Vos propres thèmes, générés au démarrage depuis des tokens daisyUI — sans étape de build. Racine uniquement en multi-spec. Voir le guide des thèmes.

language

language.defaultpar défaut"browser"

Langue de l’interface au premier chargement : "browser" suit les navigator.languages du lecteur dans available ; un code de langue l’épingle. La préférence persistée du lecteur gagne ensuite.

language.available

Langues offertes. L’anglais est dans le bundle ; les autres se téléchargent à la demande.

Environnements

environmentspar défaut[]

Environnements pré-remplis au premier chargement : { name, baseUrl, variables, defaultHeaders }. Une variable est { value, sensitive } ; les sensibles sont masquées à l’affichage et caviardées dans l’historique et les exports. Après le premier chargement, le stockage du lecteur fait foi.

environmentsLockedpar défautfalse

true retire tout point d’entrée de création ou d’édition des environnements — seul le sélecteur reste. Pour les déploiements d’entreprise contrôlés.

Contenu : docsPages, feedback et scenarios

docsPagespar défaut[]

Pages de prose tissées dans la nav : { slug, title, url } — ou content (le texte lui-même) ou contentId (id d’un élément script non exécutable de la page hôte) à la place de url. Ajoutez kind: "changelog" pour rendre les h2 d’une page en frise de versions ; nav: "bottom" sur une entrée de premier niveau l’envoie en zone d’annexe sous la référence API. Groupes, liens externes, tables multilingues, prise de contrôle de l’accueil (home: true) et forme manifeste JSON : tout est dans le guide des pages de prose.

feedback.urlpar défautnull

Votre endpoint pour la ligne « Cette page vous a-t-elle été utile ? » des pages de prose, qui envoie en POST { "page": "<slug>", "verdict": "up" | "down" } en JSON. Pas d’URL, pas de ligne — l’app n’envoie jamais rien nulle part d’elle-même. En cross-origin, le type de contenu JSON en fait une requête préliminaire. Surchargeable par spec.

scenariospar défaut[]

Scénarios livrés avec la doc : { id, title, url } vers des fichiers exportés ; pinned: true en met un en avant sur la page d’accueil. En multi-spec, déclarés uniquement sur les entrées specs[]. Voir écrire des scénarios.

announcements

Nouveau en v0.2.0 : un bandeau au-dessus de l’en-tête, pour ce que le schéma ne peut pas dire — une fenêtre de maintenance, une date de dépréciation, une version qui vient de sortir.

announcementspar défaut[]

Soit un tableau d’entrées, soit l’URL d’un fichier contenant { "announcements": [ … ] } — c’est cette seconde forme que vos ops éditent seuls, sans redéployer la page hôte. En multi-spec, racine et spec s’accumulent ; un fichier désigné remplace ce que la config déclarait. Un fichier qui ne charge pas est abandonné en silence : un bandeau que personne ne reçoit est invisible de toute façon.

announcements[].text

Le message, en Markdown inline : une chaîne, ou une par langue ({ en: "…", fr: "…" }). Assaini comme tout contenu externe.

announcements[].levelpar défaut"info"

"info", "success", "warning" ou "error".

announcements[].dismissiblepar défauttrue

false maintient le bandeau à l’écran, quoi que le lecteur ait déjà écarté.

announcements[].startsAt / .endsAt

Des instants ISO. La fenêtre est lue au rendu de la page : une maintenance déclarée une semaine à l’avance se publie et se retire toute seule — mais une entrée dont la fenêtre s’ouvre pendant qu’un onglet reste ouvert attend le chargement suivant. Une date illisible élargit la fenêtre au lieu de la fermer.

announcements[].id

La clé sous laquelle le rejet du lecteur est mémorisé. Sans id, c’est le texte déclaré qui sert d’empreinte : modifier le message le réaffiche à tout le monde, et poser un id achète l’inverse — une faute corrigée qui ne rouvre rien.

features

features.scenariospar défauttrue

false retire la fonctionnalité scénarios en entier — nav, boutons de capture, routes, index de recherche. Les scénarios locaux déjà stockés survivent, intacts, pour le jour où elle est réactivée.

features.auditpar défauttrue

false retire la page d’audit de schéma : le bloc des réglages, la route #/audit, tout calcul. La ligne de commande l’ignore.

features.onboardingpar défautfalse

true ajoute une page « Premier appel » générée (#/first-call) en tête de la nav de référence : le GET le plus simple que le schéma déclare, guidé dans la vraie console — langage, identifiants, Envoyer. Absente quand le schéma ne déclare aucune lecture de ce genre. Voir Authentification & onboarding.

features.cipar défauttrue

false retire le panneau « Automatiser ce scénario » — la remise CI. L’export Arazzo du menu du scénario reste.

audit

La configuration des règles de l’audit, lue par la page #/audit comme par apiglow audit : la note publiée et celle de la CI concordent. Une note calculée avec elle porte la mention « Règles personnalisées » partout où elle apparaît. Le guide de l’audit détaille l’ordre de priorité.

audit.rulespar défaut{}

Identifiant de règle → "error", "warning", "info" ou "off", pour tout le document. apiglow audit --list-rules imprime chaque identifiant.

audit.overridespar défaut[]

Les mêmes réglages sous des motifs de pointeurs JSON : { paths, rules, reason }. * couvre l’intérieur d’un segment, ** un nombre quelconque de segments ; la dernière correspondance l’emporte. reason est un texte libre pour le prochain lecteur.

Une entrée fautive est signalée dans la console du navigateur puis ignorée ; la ligne de commande, elle, refuse de tourner.

branding

branding.productName

Nom affiché dans l’en-tête.

branding.logoUrlpar défautnull

URL d’un logo affiché dans l’en-tête.

tryIt

tryIt.proxyUrlpar défautnull

Gabarit de proxy CORS optionnel, {{target}} = URL cible encodée. L’app ne fournit aucun proxy — vous l’hébergez.

tryIt.requestCredentialspar défaut"same-origin"

Mode credentials des fetch de la console d’essai : "omit", "same-origin" ou "include". "include" est requis pour l’auth par cookie de session cross-origin, avec les contraintes serveur détaillées dans Console d’essai & CORS.

history

history.maxEntriespar défaut500

Purge de l’historique au-delà de ce nombre (le premier seuil atteint l’emporte).

history.maxAgeDayspar défaut30

…ou au-delà de cet âge. Racine uniquement : la rétention est un plafond de stockage navigateur, partagé par toutes les specs.

oauth

oauthpar défaut{}

Par scheme OAuth2 (clé = son nom dans securitySchemes) : { clientId } utilisé par les flows dans le navigateur, surchargeable par la variable d’environnement auth.X.clientId. Jamais de client secret — la page hôte est publique.

seo

seo.indexpar défauttrue

false injecte <meta name="robots" content="noindex"> avant le premier rendu. Racine uniquement : une page est servie à une URL, et un crawler la lit sans choisir de spec. C’est une requête aux crawlers de bonne volonté, pas une protection. Ajoutez un en-tête X-Robots-Tag pour couvrir les fichiers non HTML. Voir SEO & CLI bake.

Une capacité n’a aucune clé. Les identifiants fournis par l’hôte passent par une API d’exécution (window.apidoc), pour qu’un jeton ne puisse pas finir écrit dans la config — voir le pont d’identifiants hôte. Le correctif local de schéma d’un lecteur est presque aussi privé : openapi.userOverlay amorce son état d’ouverture, et aucun drapeau ne le désactive. Il ne change que la vue d’un navigateur sur le document, et vos règles hide s’appliquent toujours après lui.

Surcharges par spec (multi-spec)

Dans une installation openapi.specs[], la config racine est le repli et presque toute clé peut être redéclarée sur une entrée. Quatre règles décident de la fusion :

• Les objets de réglages (tryIt, branding, theme, language, features, oauth) fusionnent clé par clé et la spec gagne. Une clé déclarée à null gagne aussi, donc une spec peut désactiver le proxy racine. audit fusionne ses rules de la même façon et additionne ses overrides, celles de la racine d’abord.
• Les listes nommées (docsPages par slug, environments par nom) fusionnent par identifiant, et la spec gagne.
• hide et overlays s’accumulent. Un masquage ne se démasque pas ; les overlays s’appliquent racine d’abord, puis ceux de l’entrée.
• environmentsLocked est remplacé s’il est déclaré.

Quatre clés font exception. history est racine uniquement : la rétention est un plafond de stockage navigateur commun à toutes les specs. theme.custom est racine uniquement : les thèmes sont injectés une fois au démarrage. seo est racine uniquement : l’indexabilité décrit la page servie, que toutes les specs partagent. Et scenarios va dans l’autre sens — déclarez-les uniquement sur les entrées specs[], puisqu’un scénario référence les opérations d’une spec précise. Chaque cas est nommé en console quand une config se trompe.