Skip to main content
Use OpenAPI Overlays to modify an OpenAPI specification without editing its source file. Overlays are separate JSON or YAML files that describe an ordered list of changes, which is useful when a specification is generated by another tool or maintained by another team. Common uses include renaming paths, replacing server URLs, removing internal endpoints, and adding x-mint extensions. Overlays apply after a specification is parsed and before it is validated, so generated endpoint pages, navigation, openapi frontmatter references, and mint validate all use the transformed document. Overlay Specification versions 1.0 and 1.1 are supported.

Create an overlay document

An overlay document has an overlay version, an info object with a title and version, and an actions array. Each action selects nodes with a target RFC 9535 JSONPath expression and applies one modifier:
  • update: Merges a value into each targeted node. Objects merge recursively, arrays append the value, and primitives are replaced.
  • remove: Deletes each targeted node when set to true.
  • copy: Copies the node selected by another JSONPath expression into each targeted node. Requires Overlay 1.1.
docs-overlay.yaml
The optional extends field links an overlay to a specification for auto-discovery. Set it to a path relative to the overlay file, or to the exact URL your docs.json uses for a hosted specification.

Reference overlays in your docs.json

List overlays with the object form of the openapi field, which works anywhere openapi is accepted, including inside arrays. Overlays apply in the order you list them.
docs.json
Overlay paths must point to files inside your docs repository, and overlay URLs must use https. Referencing the same specification with different overlays lists in different places fails the build.

Auto-discover overlays

Any JSON or YAML file in your repository with a top-level overlay key is treated as an overlay document. If its extends field resolves to one of your specifications, the overlay applies to that specification automatically. Auto-discovered overlays apply in alphabetical order of their file paths. Overlays without an extends field never apply automatically. An explicit overlays list replaces auto-discovery for that specification. Set "overlays": [] to disable all overlays for a specification, including auto-discovered ones. Explicit and auto-discovered overlays fail differently. If an explicit overlay fails to load or apply, the specification fails validation and the deployment reports a spec error. If an auto-discovered overlay fails, it is skipped and the specification publishes without it.

Rename a path

The Overlay Specification has no move action. To rename a path, create the new path with update, copy the existing path item into it with copy, then delete the old path with remove.
rename-overlay.yaml
Reference the transformed specification everywhere in your docs. For example, page frontmatter must use the post-overlay path: openapi: "POST /credit/accounts".

Test overlays locally

In mint dev, editing or deleting an overlay file rebuilds the affected specifications. mint validate and mint openapi-check validate the transformed document, so errors reference your specification after overlays apply.