# Une page, une config, un script.

> Installer ApiGlow en une balise script : le snippet canonique, openapi.url ou openapi.spec, l'auto-hébergement depuis npm, et un prompt pour votre agent.
>
> Source: https://apiglow.dev/fr/docs/install/index.md


## L'installation complète

{{< install-snippet >}}

C'est l'installation complète, pas un extrait. `app.js` s'initialise seul : il lit le bloc de config, injecte son propre CSS depuis l'emplacement du bundle, et construit l'interface dans la page. Il n'y a rien à builder, à générer ni à faire tourner côté serveur.

Le `src` ci-dessus pointe vers un CDN public. Pour ne dépendre de rien en dehors de votre propre origine, [servez le bundle vous-même depuis npm](#lhéberger-vous-même-depuis-npm). Seule cette ligne change.

Deux choses à savoir sur le bloc de config :

- Son id est `api-doc-config`, et le repli global `window.API_DOC_CONFIG`. Le préfixe `apidoc` est délibéré et stable, pour qu'un renommage du produit n'invalide jamais une page déployée ni les données stockées chez ses lecteurs. Recopiez-le tel quel — ne le remplacez pas par `apiglow`.
- C'est du JSON strict, puisqu'il vit dans un script `type="application/json"` : pas de commentaires, pas de virgule finale. Pour garder des commentaires dans votre config, passez par le repli `window.API_DOC_CONFIG` dans un script classique.

## `openapi.url` ou `openapi.spec`

Une clé est requise : où se trouve le schéma.

- `openapi.url` pointe vers un document OpenAPI 3.0.x, 3.1.x ou 3.2.x, JSON ou YAML. Un document Swagger 2.0 est converti au chargement. Si le serveur qui l'héberge n'est pas l'origine de la doc, il doit autoriser la lecture cross-origin — voir [Console d'essai & CORS](/fr/docs/cors/).
- `openapi.spec` transporte le document lui-même, objet JS ou chaîne JSON. Aucune requête, donc aucun CORS à négocier. En échange, la page porte le poids du schéma et doit être redéployée à chaque évolution de l'API.

Si les deux sont posés, `spec` gagne. Pour plusieurs API dans une même installation, utilisez `openapi.specs` : il a [son propre guide](/fr/docs/multi-spec/).

## Une config plus complète

Tout ce qui dépasse `openapi` a une valeur par défaut. Le bloc ci-dessous montre la forme des options courantes ; la [référence de configuration](/fr/docs/configuration/) documente chaque clé.

```json {title="api-doc-config"}
{
  "openapi": { "url": "https://example.com/openapi.json" },
  "theme": { "default": "light", "available": ["light", "dark", "corporate"] },
  "language": { "default": "en", "available": ["en", "fr"] },
  "environments": [],
  "docsPages": [],
  "scenarios": [],
  "features": { "scenarios": true, "audit": true },
  "tryIt": { "proxyUrl": null },
  "history": { "maxEntries": 500, "maxAgeDays": 30 }
}
```

## Hébergement

N'importe quel hébergement statique HTTP(S) fonctionne : un bucket S3, GitHub Pages, un dossier derrière nginx.

**`file://` ne fonctionne pas.** L'app est un module ES et télécharge ses ressources, deux choses que le navigateur bloque depuis un fichier local. Pour un aperçu en local, utilisez un serveur statique en une ligne comme `npx serve` ou `python3 -m http.server`.

## L'héberger vous-même, depuis npm

Le snippet ci-dessus charge le bundle depuis un CDN public. Pour que votre documentation ne dépende de rien en dehors de votre propre origine — un intranet, un réseau coupé du monde, une CSP sans tiers dedans — installez le paquet et servez son `dist/` vous-même. Une ligne du snippet change.

```bash {title="Une fois, dans votre build"}
npm install apiglow
cp -r node_modules/apiglow/dist static/apiglow
```

```html {title="index.html"}
<script src="/apiglow/app.js" type="module"></script>
```

Le bloc de config ne bouge pas. Vous y gagnez la version figée dans votre lockfile, relue et mise à jour comme n'importe quelle dépendance, et plus aucune requête qui sort de votre origine à l'exécution.

Ce que votre build fait déjà pour publier des fichiers statiques suffira : le `publicDir` de Vite, un plugin de copie webpack, un `cp -r` en CI. Il n'y a rien à compiler.

**Gardez `app.js` avec le reste de `dist/`.** Il résout `app.css`, les packs de langue `i18n/` et `fonts/` relativement à lui-même, ainsi que deux scripts qu'il ne charge qu'au besoin : `audit.js` quand quelqu'un ouvre l'[audit de schéma](/fr/docs/audit/), `read-document.js` pour un schéma qui contient une erreur de syntaxe. Tous doivent rester voisins où que vous les publiiez. Copiez le dossier, pas le fichier.

C'est cette même résolution qui explique qu'ApiGlow ne passe pas par un bundler JavaScript. Fondu dans l'un de vos chunks, `app.js` cherche sa feuille de style et ses packs de langue à côté de votre code, ne trouve ni l'une ni les autres, et rend la documentation sans aucun style. Installez-le, servez-le, et pointez une balise `<script>` dessus.

## Laissez faire un agent

Si c'est un agent qui installe, donnez-lui ce prompt tel quel :

{{< ai-prompt label="Faites installer par un agent" >}}