Update from code changes: document OpenAPI overlay support

[mintlify]

Summary

Mintlify now supports the OpenAPI Overlay Specification (versions 1.0 and 1.1) for transforming OpenAPI specs without editing their source files. Overlays can be listed explicitly with a new overlays array on the object form of the openapi config, or auto-discovered from repo files with a top-level overlay key and an extends link. Overlays apply before validation, so generated pages, frontmatter references, and mint validate all see the transformed document. Feature PRs: https://github.com/mintlify/mint/pull/10770 and https://github.com/mintlify/server/pull/7977

Changes

• api-playground/openapi-setup.mdx: new "Transform your spec with overlays" section covering overlay documents and actions (update, remove, copy), explicit overlays config, auto-discovery via extends, ordering and opt-out rules, failure behavior (explicit overlay failures fail validation; auto-discovered failures are skipped), and a path-rename example.
• organize/settings-api.mdx: overlays field on the api.openapi object with an example.
• organize/settings-reference.mdx: updated api.openapi type signature.
• reference/glossary.mdx: "Overlay" entry.
• French, Spanish, and Chinese translations of all changes (fr/, es/, zh/ mirrors), preserving English anchor slugs and language-prefixed internal links.
• Trimmed the zh/api-playground/openapi-setup.mdx description to CJK length guidelines.

Context

The feature author has a separate open docs PR (#7261) for the same feature; maintainers may prefer one or merge the two.

Update history

• Documented OpenAPI overlay support (config, auto-discovery, actions, rename example) with fr/es/zh translations, from https://github.com/mintlify/mint/pull/10770
• Added overlay failure behavior on hosted deployments (explicit overlay failures fail spec validation; auto-discovered failures are skipped and the raw spec publishes), mirrored in fr/es/zh, from https://github.com/mintlify/server/pull/7977

---

Note

Low Risk
Documentation-only changes with no runtime or config schema implementation in this repo.

Overview
Documents OpenAPI Overlay support (spec 1.0/1.1) so teams can transform specs without editing source files.

Adds a Transform your spec with overlays section to OpenAPI setup: overlay actions (update, remove, copy), wiring via the object form of openapi with an overlays array, auto-discovery via top-level overlay + extends, ordering/opt-out ("overlays": []), build rules (conflicting overlay lists fail the build), and different failure behavior for explicit vs auto-discovered overlays. Includes a path-rename recipe and notes that validation and frontmatter must use post-overlay paths.

Updates api.openapi in settings API/reference (new overlays field and example), adds a glossary Overlay entry, mirrors everything in es, fr, and zh (with English anchor IDs), and shortens the Chinese OpenAPI setup page description.

^{Reviewed by Cursor Bugbot for commit e4ac997. Bugbot is set up for automated code reviews on this repo. Configure here.}

[mintlify]

Preview deployment for your docs. Learn more about Mintlify Previews.

Project	Status	Preview	Updated
mintlify	🟢 Ready	View Preview	Sep 6, 2026, 6:58 AM

[mintlify]

Preview deployment for your docs. Learn more about Mintlify Previews.

Project	Status	Preview	Updated
tomee	🟡 Building	–	Sep 6, 2026, 6:56 AM

💡 Tip: Enable Automations to automatically generate PRs for you.

[mintlify]

Update from code changes updated this PR.

Verified best-practices pass; nothing new added

Source PRs

• mintlify/server#7977 — feat(openapi): apply OpenAPI Overlays in update and schema-graph workflows