OpenAPI Overlay, applied at load — fix a schema you don't own.

openapi.overlays declares OpenAPI Overlay 1.1 documents — by URL or inline — applied to the schema before anything reads it. Retitle an operation, add the examples the vendor forgot, drop an internal path: the schema you render is fixed without forking the file, and the download button serves the overlaid document your readers actually saw. Targets are full RFC 9535 JSONPath — filters, slices, unions included, not just the toy subset. An action that cannot apply is listed in the settings panel’s diagnostics and echoed to the console; it never breaks the load and never silently does nothing.

{
  "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 }
        ]
      }
    ]
  }
}

The same lever, handed to the person reading. A parameter typed string that the server only accepts as a number, a servers entry nobody filled in — and the schema belongs to another team. From the settings panel, the reader writes their own Overlay 1.1 document, applied after everything you declared: Check dry-runs it and counts what each action would touch, Save & reload applies it, and Download hands them overlay-{spec}.json — a standard file to attach to the bug report, because a workaround’s natural end state is upstream. A patched schema is never quiet about it: a permanent badge in the header, and the reader’s document listed as theirs in the diagnostics next to yours. You cannot switch it off, and you lose nothing if they use it — it changes one browser’s view, your hiding rules still apply, and the audit then grades the document actually in use.

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

Two ways to prune the documentation: "x-apiglow-hide": true in the schema itself — on an operation, a path item or a tag — or openapi.hide patterns in the config, with wildcards: tag:Internal, DELETE /admin/*, /admin/*, an operationId. Hidden operations vanish everywhere at once: nav, search, exports, llms.txt included.

Maximal OpenAPI support is a stated obligation of the project, not a roadmap line: an unsupported construct of a supported version is treated as a defect. OpenAPI 3.0.x, 3.1.x and 3.2.x are native — including 3.2’s query method, in: querystring and $self — JSON Schema 2020-12 keywords are rendered, circular references are handled, and Swagger 2.0 documents are converted at load. Your overlays apply to the parsed source before that conversion — an overlay written against the 2.0 file you actually have still works.

Webhooks and callbacks are rendered like the rest of the surface, and a webhook simulator sends the sample delivery from the browser, so receivers can be exercised without waiting for the real event. When the fixes land in the schema itself, the audit re-grades the result, and change highlights show returning readers what moved.

Hidden endpoints are documentation-level pruning: the browser still downloads the full schema, and anyone can read it in the network tab. Hiding declutters the docs; it does not control access. Never use it as a security measure.