# Toutes les clés, une page.

> La référence complète de la config ApiGlow : chaque clé du bloc JSON inline, sa valeur par défaut, et les règles de surcharge par spec.
>
> Source: https://apiglow.dev/fr/docs/configuration/index.md


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 v{{< app-version >}}.

L’objet complet en un seul bloc copiable, un commentaire par clé, vit sur [Référence complète](/fr/docs/full-reference/) — et [le builder](/fr/docs/builder/) l’écrit pour vous, station par station.

## `openapi`

| Clé | Ce qu'elle fait |
|---|---|
| `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](/fr/docs/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](/fr/docs/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](/fr/docs/schema-support/). |
| `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](/fr/docs/schema-support/). |
| `openapi.userOverlay` | Un correctif de départ amorcé dans l'[éditeur d'overlay du lecteur](/fr/docs/schema-support/#quand-cest-le-lecteur-qui-est-bloqué) (`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`

| Clé | Défaut | Ce qu'elle fait |
|---|---|---|
| `theme.default` | `"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.available` | `["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](/fr/docs/theming/). |

## `language`

| Clé | Défaut | Ce qu'elle fait |
|---|---|---|
| `language.default` | `"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

| Clé | Défaut | Ce qu'elle fait |
|---|---|---|
| `environments` | `[]` | 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. |
| `environmentsLocked` | `false` | `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`

| Clé | Défaut | Ce qu'elle fait |
|---|---|---|
| `docsPages` | `[]` | 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](/fr/docs/docs-pages/). |
| `feedback.url` | `null` | 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. |
| `scenarios` | `[]` | 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](/fr/docs/scenarios/). |

## `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.

| Clé | Défaut | Ce qu'elle fait |
|---|---|---|
| `announcements` | `[]` | 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[].level` | `"info"` | `"info"`, `"success"`, `"warning"` ou `"error"`. |
| `announcements[].dismissible` | `true` | `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`

| Clé | Défaut | Ce qu'elle fait |
|---|---|---|
| `features.scenarios` | `true` | `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.audit` | `true` | `false` retire la page d'[audit de schéma](/fr/docs/audit/) : le bloc des réglages, la route `#/audit`, tout calcul. La [ligne de commande](/fr/docs/audit-ci/) l'ignore. |
| `features.onboarding` | `false` | `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](/fr/docs/auth/). |
| `features.ci` | `true` | `false` retire le panneau « Automatiser ce scénario » — la [remise CI](/fr/docs/scenarios/#le-remettre-à-votre-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`](/fr/docs/audit-ci/) : 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](/fr/docs/audit/#configurer-les-règles) détaille l'ordre de priorité.

| Clé | Défaut | Ce qu'elle fait |
|---|---|---|
| `audit.rules` | `{}` | Identifiant de règle → `"error"`, `"warning"`, `"info"` ou `"off"`, pour tout le document. `apiglow audit --list-rules` imprime chaque identifiant. |
| `audit.overrides` | `[]` | 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`

| Clé | Défaut | Ce qu'elle fait |
|---|---|---|
| `branding.productName` | — | Nom affiché dans l'en-tête. |
| `branding.logoUrl` | `null` | URL d'un logo affiché dans l'en-tête. |

## `tryIt`

| Clé | Défaut | Ce qu'elle fait |
|---|---|---|
| `tryIt.proxyUrl` | `null` | Gabarit de proxy CORS optionnel, `{{target}}` = URL cible encodée. L'app ne fournit aucun proxy — vous l'hébergez. |
| `tryIt.requestCredentials` | `"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](/fr/docs/cors/). |

## `history`

| Clé | Défaut | Ce qu'elle fait |
|---|---|---|
| `history.maxEntries` | `500` | Purge de l'historique au-delà de ce nombre (le premier seuil atteint l'emporte). |
| `history.maxAgeDays` | `30` | …ou au-delà de cet âge. Racine uniquement : la rétention est un plafond de stockage navigateur, partagé par toutes les specs. |

## `oauth`

| Clé | Défaut | Ce qu'elle fait |
|---|---|---|
| `oauth` | `{}` | 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`

| Clé | Défaut | Ce qu'elle fait |
|---|---|---|
| `seo.index` | `true` | `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](/fr/docs/seo/). |

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](/fr/docs/auth/#quand-la-page-hôte-a-déjà-une-session). Le [correctif local de schéma](/fr/docs/schema-support/#quand-cest-le-lecteur-qui-est-bloqué) 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.