OpenAPI Overlay, appliqué au chargement — corrigez un schéma qui ne vous appartient pas.

openapi.overlays déclare des documents OpenAPI Overlay 1.1 — par URL ou en ligne — appliqués au schéma avant que quoi que ce soit le lise. Retitrer une opération, ajouter les exemples que l’éditeur a oubliés, supprimer un chemin interne : le schéma rendu est corrigé sans forker le fichier, et le bouton de téléchargement sert le document overlayé, celui que vos lecteurs ont vraiment vu. Les cibles sont du JSONPath RFC 9535 complet — filtres, tranches, unions compris, pas seulement le sous-ensemble jouet. Une action inapplicable est listée dans les diagnostics du panneau de réglages et répétée en console ; elle ne casse jamais le chargement et ne fait jamais rien en silence.

{
  "openapi": {
    "url": "https://example.com/openapi.json",
    "overlays": [
      {
        "overlay": "1.1.0",
        "info": { "title": "Docs fixes", "version": "1" },
        "actions": [
          {
            "target": "$.paths['/pets'].get",
            "update": { "summary": "List pets" }
          },
          { "target": "$.paths['/internal']", "remove": true }
        ]
      }
    ]
  }
}

Le même levier, mis entre les mains de qui lit. Un paramètre typé string que le serveur n’accepte qu’en nombre, une entrée servers que personne n’a remplie — et le schéma appartient à une autre équipe. Depuis le panneau de réglages, le lecteur écrit son propre document Overlay 1.1, appliqué après tout ce que vous avez déclaré : Vérifier l’exécute à blanc et compte ce que chaque action toucherait, Enregistrer et recharger l’applique, et Télécharger lui rend un overlay-{spec}.json — un fichier standard à joindre au rapport de bug, parce que la fin naturelle d’un contournement, c’est l’amont. Un schéma corrigé ne le cache jamais : badge permanent dans l’en-tête, et le document du lecteur listé comme le sien dans les diagnostics, à côté des vôtres. Vous ne pouvez pas le désactiver, et vous n’y perdez rien : cela ne change que la vue d’un navigateur, vos règles de masquage s’appliquent toujours, et l’audit note alors le document réellement en usage.

{
  "overlay": "1.1.0",
  "info": { "title": "Local fixes", "version": "1" },
  "actions": [
    {
      "target": "$.paths['/orders'].post.parameters[?@.name=='shopId']",
      "update": { "schema": { "type": "integer" } }
    }
  ]
}

Deux façons d’élaguer la documentation : "x-apiglow-hide": true dans le schéma lui-même — sur une opération, un path item ou un tag — ou des motifs openapi.hide dans la config, jokers compris : tag:Internal, DELETE /admin/*, /admin/*, un operationId. Les opérations masquées disparaissent partout à la fois : navigation, recherche, exports, llms.txt compris.

Le support OpenAPI maximal est une obligation affichée du projet, pas une ligne de roadmap : une construction non supportée d’une version supportée est traitée comme un défaut. OpenAPI 3.0.x, 3.1.x et 3.2.x sont natifs — y compris la méthode query, in: querystring et $self de la 3.2 — les mots-clés JSON Schema 2020-12 sont rendus, les références circulaires gérées, et les documents Swagger 2.0 convertis au chargement — vos overlays s’appliquent au source parsé avant cette conversion : un overlay écrit contre le fichier 2.0 que vous avez vraiment fonctionne tel quel.

Les webhooks et callbacks sont rendus comme le reste de la surface, et un simulateur de webhook envoie la livraison d’exemple depuis le navigateur — de quoi exercer un récepteur sans attendre l’événement réel. Quand les corrections atterrissent dans le schéma lui-même, l’audit renote le résultat, et le suivi des changements montre aux lecteurs qui reviennent ce qui a bougé.

Les endpoints masqués relèvent de l’élagage documentaire : le navigateur télécharge toujours le schéma complet, et n’importe qui peut le lire dans l’onglet réseau. Le masquage désencombre la doc ; il ne contrôle aucun accès. Ne l’utilisez jamais comme mesure de sécurité.