From 7346d10000114e10ebcf4a824c524d9faf9f2c9c Mon Sep 17 00:00:00 2001 From: brandonmcconnell Date: Thu, 3 Sep 2026 17:29:30 -0700 Subject: [PATCH] docs: OpenAPI Overlay support (explicit overlays in docs.json, extends auto-discovery, precedence, actions) Co-authored-by: Cursor --- api-playground/openapi-setup.mdx | 76 ++++++++++++++++++++++++++++++++ organize/settings-api.mdx | 12 ++++- organize/settings-reference.mdx | 4 +- 3 files changed, 89 insertions(+), 3 deletions(-) diff --git a/api-playground/openapi-setup.mdx b/api-playground/openapi-setup.mdx index f07183ed7f..2bb3396d40 100644 --- a/api-playground/openapi-setup.mdx +++ b/api-playground/openapi-setup.mdx @@ -187,6 +187,82 @@ The `x-default` extension supports `apiKey` and `http` bearer security scheme ty Use `x-default` on other schema properties in your OpenAPI specification to set a default value in the API playground without affecting the `default` field in the schema definition. Unlike security schemes, prefill for non-security-scheme properties only takes effect when you set [`api.examples.prefill`](/organize/settings-api) to `true` in your [`docs.json`](/api-playground/overview#example-configuration). +## Apply OpenAPI Overlays + +Use [OpenAPI Overlays](https://spec.openapis.org/overlay/v1.1.0.html) to modify your OpenAPI specifications without editing the source files. Overlays are separate JSON or YAML documents that describe an ordered list of changes to apply to a specification before Mintlify validates it and generates your documentation. Overlays are useful when your specifications are generated by other tools and you need to adjust them for your public documentation, for example to rewrite paths, replace server URLs, or remove internal fields. + +Mintlify supports the full Overlay Specification 1.1.0, including the `update`, `remove`, and `copy` actions. The `target` of each action is a [RFC 9535 JSONPath](https://www.rfc-editor.org/rfc/rfc9535) expression. + +An overlay document requires an `overlay` version, an `info` object, and at least one action: + +```yaml publish-paths.overlay.yaml +overlay: 1.1.0 +info: + title: Publish credit paths + version: 1.0.0 +extends: ../specs/credit.yaml +actions: + - target: $.paths + update: { "/credit/accounts": {} } + - target: $.paths["/credit/accounts"] + copy: $.paths["/accounts"] + - target: $.paths["/accounts"] + remove: true + - target: $.servers[0].url + update: https://api.example.com/v3 +``` + +This example renames the internal `/accounts` path to the public `/credit/accounts` path using the `update`, `copy`, and `remove` sequence, then replaces the server URL. + +### Reference overlays in docs.json + +Reference overlay files explicitly with the `overlays` property anywhere you reference an OpenAPI specification. Overlays apply in the order they are listed. Overlay files can be relative paths in your repository or `https` URLs. + +```json +"navigation": { + "tabs": [ + { + "tab": "API Reference", + "openapi": { + "source": "specs/credit.yaml", + "overlays": ["overlays/publish-paths.overlay.yaml"] + } + } + ] +} +``` + +Arrays of specifications can mix plain strings and objects with overlays: + +```json +"openapi": [ + "specs/simple.yaml", + { + "source": "specs/credit.yaml", + "overlays": ["overlays/publish-paths.overlay.yaml"] + } +] +``` + +### Auto-discover overlays with extends + +Any JSON or YAML file in your repository with a top-level `overlay` field is treated as an overlay document. If the overlay's `extends` field resolves to a specification in your repository (as a path relative to the overlay file) or matches the exact URL of a hosted specification, the overlay applies to that specification automatically, without any `docs.json` changes. + +Overlays without an `extends` field, or with an `extends` value that doesn't resolve to a known specification, are never applied. + +### Precedence and ordering + +- An explicit `overlays` list in `docs.json` takes precedence and suppresses auto-discovered overlays for that specification. +- An empty list (`"overlays": []`) disables all overlays for that specification, including auto-discovered ones. +- When multiple auto-discovered overlays extend the same specification, they apply in alphabetical order of their file paths. +- Referencing the same specification with different `overlays` lists in different places is an error. Use the same list everywhere the specification is referenced. + + + Overlays apply before validation and page generation, so everything downstream sees the transformed document: the API playground, generated endpoint pages, and `openapi` frontmatter matching. Reference post-overlay paths in your MDX frontmatter. For example, if an overlay renames `/accounts` to `/credit/accounts`, use `openapi: "POST /credit/accounts"`. + + +Run `mint validate` to check your specifications with overlays applied. Overlay errors report the overlay file, the failing action, and its target expression. + ## Let visitors download your spec Opt into a "Download API spec" entry in the [page context menu](/organize/settings-structure#contextual) by adding `"download-spec"` to `contextual.options` in your `docs.json`: diff --git a/organize/settings-api.mdx b/organize/settings-api.mdx index af4007e971..b1f5a82c3b 100644 --- a/organize/settings-api.mdx +++ b/organize/settings-api.mdx @@ -15,7 +15,7 @@ Use the `api` field in `docs.json` to configure what API specifications generate Define all API-related settings under the `api` key. - OpenAPI specification files for generating API reference pages. Accepts a single path or URL, an array of paths and URLs, or an object specifying a source and directory. + OpenAPI specification files for generating API reference pages. Accepts a single path or URL, an array of paths, URLs, and objects, or an object specifying a source, directory, and overlays. @@ -24,6 +24,9 @@ Define all API-related settings under the `api` key. Directory to search for OpenAPI files. Do not include a leading slash. + + Paths or URLs of [OpenAPI Overlay](/api-playground/openapi-setup#apply-openapi-overlays) documents to apply to the source specification, in order. An empty array disables all overlays for this specification, including auto-discovered ones. + @@ -47,6 +50,13 @@ Define all API-related settings under the `api` key. } ``` + ```json Overlays + "openapi": { + "source": "openapi.json", + "overlays": ["overlays/publish-paths.overlay.yaml"] + } + ``` + diff --git a/organize/settings-reference.mdx b/organize/settings-reference.mdx index 1e4defea10..b7e9bf634e 100644 --- a/organize/settings-reference.mdx +++ b/organize/settings-reference.mdx @@ -757,9 +757,9 @@ API documentation and playground settings. #### `api.openapi` -OpenAPI specification files. +OpenAPI specification files. Objects accept `source` (string), `directory` (string), and `overlays` (array of string) for [OpenAPI Overlay](/api-playground/openapi-setup#apply-openapi-overlays) documents applied to the source specification in order. -**Type:** string | array of string | object with `source` (string) and `directory` (string) +**Type:** string | array of string or object | object with `source` (string), `directory` (string), and `overlays` (array of string) #### `api.asyncapi`