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 couvre 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 — requis, un slug stable ([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 au démarrage.
• title — le libellé du sélecteur. Il est nécessaire parce que les specs inactives ne sont jamais téléchargées, donc 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. Sans lui, c’est 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, et 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é et la spec gagne, les listes nommées fusionnent par identifiant, hide et overlays s’accumulent racine d’abord, et environmentsLocked est remplacé.

tryIt.requestCredentials est le cas le plus net : 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 :

• 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.
• scenarios est entrées uniquement — un scénario référence les opérations d’une spec précise.

Chaque cas est nommé en console quand une config le place au mauvais endroit.

Ce que couvre l’isolation

Environnements, historique de requêtes, tokens OAuth, mémoire d’en-têtes de la console d’essai, scénarios, recherche et le correctif local de schéma d’un lecteur sont tous cloisonnés 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 est la clé de stockage

Parce que id préfixe chaque clé stockée, changer l’id d’une spec réinitialise ses données locales : environnements, historique, scénarios locaux. Choisissez des ids stables, et ne les recyclez jamais.