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.1.0/dist/app.js" type="module"></script>
  </body>
</html>

Ce n’est pas un aperçu : c’est toute l’installation. app.js s’initialise seul — il lit le bloc de config, injecte son propre CSS (résolu à côté du bundle) et construit l’interface entière dans la page. Rien à builder, rien à générer, rien à faire tourner côté serveur.

Ce src pointe vers un CDN public. Si vous préférez ne dépendre de rien d’autre que votre propre origine, servez le bundle vous-même depuis npm — le bloc de config ci-dessous ne change pas, cette ligne-là seulement.

Deux détails sont volontaires et méritent d’être connus :

L’id de l’élément de config 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 — ne le « corrigez » pas en apiglow ; recopiez-le tel quel.
La config est du JSON strict (elle vit dans un script type="application/json") : pas de commentaires, pas de virgule finale. Pour garder une config commentée, passez par le repli window.API_DOC_CONFIG dans un script classique.

`openapi.url` ou `openapi.spec`

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

openapi.url pointe vers un document OpenAPI 3.0.x / 3.1.x / 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.

Plusieurs API dans la même installation ? C’est openapi.specs, qui a son propre guide.

Une config plus complète

Tout ce qui dépasse openapi a une valeur par défaut raisonnable ; 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) suffit — 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, un serveur statique en une ligne fait l’affaire (npx serve, python3 -m http.server).

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

Le snippet ci-dessus charge le bundle depuis un CDN public. Si vous préférez que votre documentation ne dépende de rien d’autre que 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 seule 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. Ce que vous y gagnez : la version figée dans votre lockfile — relue, auditée et mise à jour comme n’importe quelle dépendance — et plus une seule 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 trouve app.css, les packs de langue i18n/ et fonts/ relativement à lui-même : les quatre doivent rester voisins où que vous les publiiez — copiez le dossier, pas le fichier.

C’est cette même règle qui explique qu’ApiGlow ne passe pas par votre bundler JavaScript. Fondu dans l’un de vos chunks, app.js se met à chercher 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. L’installer, le servir, pointer une balise <script> dessus : c’est la forme prise en charge, et c’est celle qui garde l’app en un seul fichier lisible.

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