Plusieurs API, une installation.

openapi.specs transforme une installation en portail : un sélecteur dans l’en-tête, un schéma actif à la fois, et tout ce que le lecteur accumule tenu séparé par spec. La page de fonctionnalité plaide le dossier ; ce guide en est la mécanique.

Déclarer les specs

{
  "openapi": {
    "specs": [
      { "id": "payments", "title": "Payments API", "url": "https://example.com/payments.json" },
      { "id": "accounts", "title": "Accounts API", "url": "https://example.com/accounts.yaml" }
    ],
    "default": "payments"
  }
}

• id — slug stable obligatoire ([a-z0-9-]), unique dans le tableau. Il sert à la fois de segment de route (#/s/{id}/…) et de préfixe de stockage ; un id en double ou invalide est une erreur de config explicite au démarrage.
• title — le libellé du sélecteur, nécessaire parce que les specs inactives ne sont jamais téléchargées (leur info.title est inconnu). Retombe sur id.
• Chaque entrée prend url ou un spec inline. Seule la spec active est téléchargée, parsée et indexée — une installation à douze API n’en coûte qu’une au lecteur.
• default choisit la spec affichée à l’arrivée ; sinon la première entrée.

Une config mono-spec openapi.url se comporte exactement comme avant : pas de sélecteur, routes sans préfixe, mêmes clés de stockage.

Surcharger par spec

La config racine porte ce que l’installation partage ; une entrée redéclare ce qui lui est propre. Les règles de fusion sont celles de la référence de configuration : les objets de réglages fusionnent clé par clé (la spec gagne, null compris), les listes nommées fusionnent par identifiant, hide et overlays s’accumulent (racine d’abord), environmentsLocked est remplacé. La première clé qui a imposé cette mécanique est tryIt.requestCredentials : la bonne valeur dépend de l’API visée, donc elle appartient à l’entrée.

{
  "openapi": {
    "specs": [
      { "id": "payments", "title": "API Paiements", "url": "https://example.com/payments.json",
        "branding": { "productName": "Paiements" },
        "theme": { "default": "corporate", "available": ["corporate", "dark"] } },
      { "id": "accounts", "title": "API Comptes", "url": "https://example.com/accounts.yaml",
        "tryIt": { "requestCredentials": "include" },
        "environmentsLocked": true,
        "features": { "scenarios": false } }
    ]
  }
}

Trois clés ne voyagent pas, chacune signalée nommément en console quand elle est mal placée : history (racine uniquement — la rétention est un plafond de stockage navigateur, commun à toutes les specs), theme.custom (racine uniquement — les thèmes sont injectés une fois au démarrage), et scenarios (entrées uniquement — un scénario référence les opérations d’une spec précise).

L’isolation est le sujet

Environnements, historique de requêtes, tokens OAuth, mémoire d’en-têtes de la console d’essai, scénarios, recherche, le correctif local de schéma d’un lecteur — tout est cloisonné par id de spec. Deux specs déclarant un scheme du même nom (bearerAuth est partout) ne partagent jamais une variable : un token obtenu sur Payments ne peut pas être injecté dans une requête vers Accounts. Les liens profonds portent le préfixe (#/s/payments/op/…), donc un lien partagé atterrit sur la bonne API ; un lien sans préfixe s’ouvre sur la spec active.

L’id, c’est le stockage

Parce que id préfixe chaque clé stockée, changer l’id d’une spec équivaut à réinitialiser ses données locales — environnements, historique, scénarios locaux. Choisissez vos ids comme vos noms de bases de données : stables, ennuyeux, jamais recyclés.