Une page, une config, un script.

L’installation complète

index.html

<!doctype html>
<html>
  <head><title>My API docs</title></head>
  <body>
    <script id="api-doc-config" type="application/json">
    { "openapi": { "url": "https://example.com/openapi.json" } }
    </script>
    <script src="https://cdn.jsdelivr.net/npm/apiglow@0.3.0/dist/app.js" type="module"></script>
  </body>
</html>

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

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 documente chaque clé.

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.

Une fois, dans votre build

npm install apiglow
cp -r node_modules/apiglow/dist static/apiglow

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, 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 :

Faites installer par un agent

Add interactive API documentation to my project with ApiGlow
(https://apiglow.dev).

1. Create a static page (e.g. docs/index.html) containing exactly:
   - a <script id="api-doc-config" type="application/json"> block with:
     { "openapi": { "url": "<my OpenAPI schema URL or relative path>" } }
   - <script src="https://cdn.jsdelivr.net/npm/apiglow@0.3.0/dist/app.js"
     type="module"></script>
2. My OpenAPI schema is at: [FILL IN — URL or path]
3. Serve the page over HTTP(S) — file:// does not work (ES modules).
4. If my API is on another origin, tell me it must allow CORS from the
   docs origin for the try-it console to work.
Config reference: https://apiglow.dev/docs/configuration/