diff --git a/api-playground/openapi-setup.mdx b/api-playground/openapi-setup.mdx
index f07183ed7f..4786e6f658 100644
--- a/api-playground/openapi-setup.mdx
+++ b/api-playground/openapi-setup.mdx
@@ -187,6 +187,90 @@ 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).
+## Transform your spec with overlays
+
+Use [OpenAPI Overlays](https://spec.openapis.org/overlay/v1.1.0.html) 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, and removing internal endpoints.
+
+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](https://www.rfc-editor.org/rfc/rfc9535) 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.
+
+```yaml docs-overlay.yaml
+overlay: 1.1.0
+info:
+ title: Docs adjustments
+ version: 1.0.0
+extends: ./openapi.json
+actions:
+ - target: $.info.description
+ update: "The public API for Example, Inc."
+ - target: $.paths['/internal-metrics']
+ remove: true
+```
+
+The optional `extends` field links an overlay to a specification for [auto-discovery](#auto-discover-overlays). 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.
+
+```json {6-9}
+"navigation": {
+ "tabs": [
+ {
+ "tab": "API reference",
+ "openapi": {
+ "source": "openapi.json",
+ "overlays": [
+ "overlays/rename-paths.yaml",
+ "https://example.com/overlays/servers.yaml"
+ ]
+ }
+ }
+ ]
+}
+```
+
+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`.
+
+```yaml rename-overlay.yaml
+overlay: 1.1.0
+info:
+ title: Move accounts under credit
+ version: 1.0.0
+extends: ./openapi.json
+actions:
+ - target: $.paths
+ update:
+ /credit/accounts: {}
+ - target: $.paths['/credit/accounts']
+ copy: $.paths['/accounts']
+ - target: $.paths['/accounts']
+ remove: true
+```
+
+Reference the transformed specification everywhere in your docs. For example, page frontmatter must use the post-overlay path: `openapi: "POST /credit/accounts"`.
+
+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.
+
## 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/es/api-playground/openapi-setup.mdx b/es/api-playground/openapi-setup.mdx
index 8580df0023..fc9d83cbc3 100644
--- a/es/api-playground/openapi-setup.mdx
+++ b/es/api-playground/openapi-setup.mdx
@@ -202,6 +202,100 @@ También puedes usar `x-default` en otras propiedades de esquema en tu especific
El prellenado desde `x-default` en propiedades de esquema de tipo array no es compatible actualmente en el playground de la API, incluso cuando `api.examples.prefill` está habilitado.
+
+ ## Transforma tu especificación con overlays
+
+
+Usa [overlays de OpenAPI](https://spec.openapis.org/overlay/v1.1.0.html) para modificar una especificación de OpenAPI sin editar su archivo de origen. Los overlays son archivos JSON o YAML independientes que describen una lista ordenada de cambios, lo cual es útil cuando una especificación es generada por otra herramienta o mantenida por otro equipo. Los usos comunes incluyen renombrar rutas, reemplazar URLs de servidor y eliminar endpoints internos.
+
+Los overlays se aplican después de analizar una especificación y antes de validarla, por lo que las páginas de endpoints generadas, la navegación, las referencias `openapi` en el frontmatter y `mint validate` usan el documento transformado. Se admiten las versiones 1.0 y 1.1 de la Overlay Specification.
+
+
+ ### Crea un documento de overlay
+
+
+Un documento de overlay tiene una versión `overlay`, un objeto `info` con un `title` y una `version`, y un array `actions`. Cada acción selecciona nodos con una expresión `target` de [JSONPath RFC 9535](https://www.rfc-editor.org/rfc/rfc9535) y aplica un modificador:
+
+* `update`: Combina un valor en cada nodo seleccionado. Los objetos se combinan de forma recursiva, los arrays añaden el valor al final y los valores primitivos se reemplazan.
+* `remove`: Elimina cada nodo seleccionado cuando se establece en `true`.
+* `copy`: Copia el nodo seleccionado por otra expresión JSONPath en cada nodo seleccionado. Requiere Overlay 1.1.
+
+```yaml docs-overlay.yaml
+overlay: 1.1.0
+info:
+ title: Docs adjustments
+ version: 1.0.0
+extends: ./openapi.json
+actions:
+ - target: $.info.description
+ update: "The public API for Example, Inc."
+ - target: $.paths['/internal-metrics']
+ remove: true
+```
+
+El campo opcional `extends` vincula un overlay a una especificación para el [descubrimiento automático](#auto-discover-overlays). Establécelo en una ruta relativa al archivo del overlay, o en la URL exacta que tu `docs.json` usa para una especificación alojada.
+
+
+ ### Haz referencia a los overlays en tu docs.json
+
+
+Enumera los overlays con la forma de objeto del campo `openapi`, que funciona en cualquier lugar donde se acepte `openapi`, incluso dentro de arrays. Los overlays se aplican en el orden en que los enumeras.
+
+```json {6-9}
+"navigation": {
+ "tabs": [
+ {
+ "tab": "API reference",
+ "openapi": {
+ "source": "openapi.json",
+ "overlays": [
+ "overlays/rename-paths.yaml",
+ "https://example.com/overlays/servers.yaml"
+ ]
+ }
+ }
+ ]
+}
+```
+
+Las rutas de los overlays deben apuntar a archivos dentro de tu repositorio de documentación, y las URLs de los overlays deben usar `https`. Hacer referencia a la misma especificación con listas de `overlays` diferentes en distintos lugares hace que la compilación falle.
+
+
+ ### Descubrimiento automático de overlays
+
+
+Cualquier archivo JSON o YAML de tu repositorio con una clave `overlay` de nivel superior se trata como un documento de overlay. Si su campo `extends` se resuelve en una de tus especificaciones, el overlay se aplica automáticamente a esa especificación. Los overlays descubiertos automáticamente se aplican en orden alfabético según sus rutas de archivo. Los overlays sin un campo `extends` nunca se aplican automáticamente.
+
+Una lista `overlays` explícita reemplaza el descubrimiento automático para esa especificación. Establece `"overlays": []` para deshabilitar todos los overlays de una especificación, incluidos los descubiertos automáticamente.
+
+Los overlays explícitos y los descubiertos automáticamente fallan de forma distinta. Si un overlay explícito no se puede cargar o aplicar, la especificación no pasa la validación y el despliegue reporta un error de especificación. Si falla un overlay descubierto automáticamente, se omite y la especificación se publica sin él.
+
+
+ ### Renombrar una ruta
+
+
+La Overlay Specification no tiene una acción de movimiento. Para renombrar una ruta, crea la nueva ruta con `update`, copia el elemento de ruta existente en ella con `copy` y luego elimina la ruta antigua con `remove`.
+
+```yaml rename-overlay.yaml
+overlay: 1.1.0
+info:
+ title: Move accounts under credit
+ version: 1.0.0
+extends: ./openapi.json
+actions:
+ - target: $.paths
+ update:
+ /credit/accounts: {}
+ - target: $.paths['/credit/accounts']
+ copy: $.paths['/accounts']
+ - target: $.paths['/accounts']
+ remove: true
+```
+
+Haz referencia a la especificación transformada en toda tu documentación. Por ejemplo, el frontmatter de una página debe usar la ruta posterior al overlay: `openapi: "POST /credit/accounts"`.
+
+En `mint dev`, editar o eliminar un archivo de overlay reconstruye las especificaciones afectadas. `mint validate` y `mint openapi-check` validan el documento transformado, por lo que los errores hacen referencia a tu especificación después de aplicar los overlays.
+
## Permite que los visitantes descarguen tu especificación
diff --git a/es/organize/settings-api.mdx b/es/organize/settings-api.mdx
index c4eae0ba70..1976d2015c 100644
--- a/es/organize/settings-api.mdx
+++ b/es/organize/settings-api.mdx
@@ -15,7 +15,7 @@ Usa el campo `api` en `docs.json` para configurar qué especificaciones de API g
Define todos los ajustes relacionados con la API bajo la clave `api`.
- Archivos de especificación OpenAPI para generar páginas de referencia de API. Acepta una única ruta o URL, un array de rutas y URLs, o un objeto que especifica una fuente y directorio.
+ Archivos de especificación OpenAPI para generar páginas de referencia de API. Acepta una única ruta o URL, un array de rutas, URLs y objetos, o un objeto que especifica una fuente, un directorio y overlays.
@@ -24,6 +24,9 @@ Define todos los ajustes relacionados con la API bajo la clave `api`.
Directorio donde buscar archivos OpenAPI. No incluyas una barra inicial.
+
+ Rutas o URLs de documentos de [OpenAPI Overlay](/es/api-playground/openapi-setup#transform-your-spec-with-overlays) que se aplican a la especificación, en orden. Un array vacío deshabilita todos los overlays de la especificación, incluidos los descubiertos automáticamente.
+
@@ -47,6 +50,13 @@ Define todos los ajustes relacionados con la API bajo la clave `api`.
}
```
+ ```json Overlays
+ "openapi": {
+ "source": "openapi.json",
+ "overlays": ["overlays/docs-adjustments.yaml"]
+ }
+ ```
+
diff --git a/es/organize/settings-reference.mdx b/es/organize/settings-reference.mdx
index 5be3d04b01..20d78423c5 100644
--- a/es/organize/settings-reference.mdx
+++ b/es/organize/settings-reference.mdx
@@ -763,7 +763,7 @@ Configuración de documentación de API y área de pruebas.
Archivos de especificación OpenAPI.
-**Tipo:** string | array of string | object con `source` (string) y `directory` (string)
+**Tipo:** string | array of string u object | object con `source` (string), `directory` (string) y `overlays` (array of string)
#### `api.asyncapi`
diff --git a/es/reference/glossary.mdx b/es/reference/glossary.mdx
index 85ac347152..bbbf9038e9 100644
--- a/es/reference/glossary.mdx
+++ b/es/reference/glossary.mdx
@@ -270,6 +270,12 @@ Un formato estándar para describir APIs HTTP. Mintlify puede generar páginas d
Un espacio de trabajo de Mintlify que contiene miembros del equipo, configuración a nivel de organización, créditos compartidos y uno o más despliegues.
+
+### Overlay
+
+
+Un documento JSON o YAML que describe cambios que se aplican a una especificación de OpenAPI sin editar su archivo de origen. Mintlify aplica los overlays antes de validar y renderizar una especificación. Consulta [Transforma tu especificación con overlays](/es/api-playground/openapi-setup#transform-your-spec-with-overlays).
+
## P
diff --git a/fr/api-playground/openapi-setup.mdx b/fr/api-playground/openapi-setup.mdx
index eb1d49c3cb..0c2a853953 100644
--- a/fr/api-playground/openapi-setup.mdx
+++ b/fr/api-playground/openapi-setup.mdx
@@ -202,6 +202,100 @@ Vous pouvez également utiliser `x-default` sur d’autres propriétés de sché
Le pré-remplissage depuis `x-default` sur des propriétés de schéma de type array n’est pas pris en charge actuellement dans le playground de l’API, même lorsque `api.examples.prefill` est activé.
+
+ ## Transformez votre spécification avec des overlays
+
+
+Utilisez les [overlays OpenAPI](https://spec.openapis.org/overlay/v1.1.0.html) pour modifier une spécification OpenAPI sans éditer son fichier source. Les overlays sont des fichiers JSON ou YAML distincts qui décrivent une liste ordonnée de modifications, ce qui est utile lorsqu’une spécification est générée par un autre outil ou maintenue par une autre équipe. Les usages courants incluent le renommage de chemins, le remplacement d’URL de serveur et la suppression d’endpoints internes.
+
+Les overlays s’appliquent après l’analyse d’une spécification et avant sa validation, de sorte que les pages d’endpoints générées, la navigation, les références `openapi` dans le frontmatter et `mint validate` utilisent tous le document transformé. Les versions 1.0 et 1.1 de la spécification Overlay sont prises en charge.
+
+
+ ### Créer un document d’overlay
+
+
+Un document d’overlay comporte une version `overlay`, un objet `info` avec un `title` et une `version`, et un tableau `actions`. Chaque action sélectionne des nœuds avec une expression `target` au format [JSONPath RFC 9535](https://www.rfc-editor.org/rfc/rfc9535) et applique un modificateur :
+
+* `update` : fusionne une valeur dans chaque nœud ciblé. Les objets fusionnent de manière récursive, les tableaux ajoutent la valeur à la fin et les primitives sont remplacées.
+* `remove` : supprime chaque nœud ciblé lorsque défini sur `true`.
+* `copy` : copie le nœud sélectionné par une autre expression JSONPath dans chaque nœud ciblé. Nécessite Overlay 1.1.
+
+```yaml docs-overlay.yaml
+overlay: 1.1.0
+info:
+ title: Docs adjustments
+ version: 1.0.0
+extends: ./openapi.json
+actions:
+ - target: $.info.description
+ update: "The public API for Example, Inc."
+ - target: $.paths['/internal-metrics']
+ remove: true
+```
+
+Le champ facultatif `extends` associe un overlay à une spécification pour la [découverte automatique](#auto-discover-overlays). Définissez-le sur un chemin relatif au fichier d’overlay, ou sur l’URL exacte que votre `docs.json` utilise pour une spécification hébergée.
+
+
+ ### Référencer les overlays dans votre docs.json
+
+
+Listez les overlays avec la forme objet du champ `openapi`, qui fonctionne partout où `openapi` est accepté, y compris à l’intérieur de tableaux. Les overlays s’appliquent dans l’ordre où vous les listez.
+
+```json {6-9}
+"navigation": {
+ "tabs": [
+ {
+ "tab": "API reference",
+ "openapi": {
+ "source": "openapi.json",
+ "overlays": [
+ "overlays/rename-paths.yaml",
+ "https://example.com/overlays/servers.yaml"
+ ]
+ }
+ }
+ ]
+}
+```
+
+Les chemins d’overlay doivent pointer vers des fichiers situés dans votre dépôt de documentation, et les URL d’overlay doivent utiliser `https`. Référencer la même spécification avec des listes `overlays` différentes à plusieurs endroits fait échouer la génération.
+
+
+ ### Découverte automatique des overlays
+
+
+Tout fichier JSON ou YAML de votre dépôt comportant une clé `overlay` de premier niveau est traité comme un document d’overlay. Si son champ `extends` correspond à l’une de vos spécifications, l’overlay s’applique automatiquement à cette spécification. Les overlays découverts automatiquement s’appliquent dans l’ordre alphabétique de leurs chemins de fichier. Les overlays sans champ `extends` ne s’appliquent jamais automatiquement.
+
+Une liste `overlays` explicite remplace la découverte automatique pour cette spécification. Définissez `"overlays": []` pour désactiver tous les overlays d’une spécification, y compris ceux découverts automatiquement.
+
+Les overlays explicites et découverts automatiquement échouent différemment. Si un overlay explicite ne peut pas être chargé ou appliqué, la spécification échoue à la validation et le déploiement signale une erreur de spécification. Si un overlay découvert automatiquement échoue, il est ignoré et la spécification est publiée sans lui.
+
+
+ ### Renommer un chemin
+
+
+La spécification Overlay ne comporte pas d’action de déplacement. Pour renommer un chemin, créez le nouveau chemin avec `update`, copiez-y l’élément de chemin existant avec `copy`, puis supprimez l’ancien chemin avec `remove`.
+
+```yaml rename-overlay.yaml
+overlay: 1.1.0
+info:
+ title: Move accounts under credit
+ version: 1.0.0
+extends: ./openapi.json
+actions:
+ - target: $.paths
+ update:
+ /credit/accounts: {}
+ - target: $.paths['/credit/accounts']
+ copy: $.paths['/accounts']
+ - target: $.paths['/accounts']
+ remove: true
+```
+
+Référencez la spécification transformée partout dans votre documentation. Par exemple, le frontmatter d’une page doit utiliser le chemin post-overlay : `openapi: "POST /credit/accounts"`.
+
+Dans `mint dev`, la modification ou la suppression d’un fichier d’overlay reconstruit les spécifications concernées. `mint validate` et `mint openapi-check` valident le document transformé, de sorte que les erreurs référencent votre spécification après l’application des overlays.
+
## Permettez aux visiteurs de télécharger votre spécification
diff --git a/fr/organize/settings-api.mdx b/fr/organize/settings-api.mdx
index e9961ef0ef..129b9819dc 100644
--- a/fr/organize/settings-api.mdx
+++ b/fr/organize/settings-api.mdx
@@ -15,7 +15,7 @@ Utilisez le champ `api` dans `docs.json` pour configurer les spécifications d'A
Définissez tous les paramètres liés à l'API sous la clé `api`.
- Fichiers de spécification OpenAPI pour générer des pages de référence d'API. Accepte un chemin ou une URL unique, un tableau de chemins et d'URL, ou un objet spécifiant une source et un répertoire.
+ Fichiers de spécification OpenAPI pour générer des pages de référence d'API. Accepte un chemin ou une URL unique, un tableau de chemins, d'URL et d'objets, ou un objet spécifiant une source, un répertoire et des overlays.
@@ -24,6 +24,9 @@ Définissez tous les paramètres liés à l'API sous la clé `api`.
Répertoire dans lequel rechercher les fichiers OpenAPI. N'incluez pas de barre oblique initiale.
+
+ Chemins ou URL de documents [OpenAPI Overlay](/fr/api-playground/openapi-setup#transform-your-spec-with-overlays) à appliquer à la spécification, dans l'ordre. Un tableau vide désactive tous les overlays pour la spécification, y compris ceux découverts automatiquement.
+
@@ -47,6 +50,13 @@ Définissez tous les paramètres liés à l'API sous la clé `api`.
}
```
+ ```json Overlays
+ "openapi": {
+ "source": "openapi.json",
+ "overlays": ["overlays/docs-adjustments.yaml"]
+ }
+ ```
+
diff --git a/fr/organize/settings-reference.mdx b/fr/organize/settings-reference.mdx
index bc00e2f8e2..021d7684ce 100644
--- a/fr/organize/settings-reference.mdx
+++ b/fr/organize/settings-reference.mdx
@@ -763,7 +763,7 @@ Paramètres de documentation et de playground d'API.
Fichiers de spécification OpenAPI.
-**Type :** string | array of string | object avec `source` (string) et `directory` (string)
+**Type :** string | array of string or object | object avec `source` (string), `directory` (string) et `overlays` (array of string)
#### `api.asyncapi`
diff --git a/fr/reference/glossary.mdx b/fr/reference/glossary.mdx
index bda2336d99..4ed2e428ee 100644
--- a/fr/reference/glossary.mdx
+++ b/fr/reference/glossary.mdx
@@ -270,6 +270,12 @@ Un format standard pour décrire les API HTTP. Mintlify peut générer des pages
Un espace de travail Mintlify qui contient les membres de l'équipe, les paramètres au niveau de l'organisation, les crédits partagés et un ou plusieurs déploiements.
+
+### Overlay
+
+
+Un document JSON ou YAML qui décrit des modifications à appliquer à une spécification OpenAPI sans éditer son fichier source. Mintlify applique les overlays avant de valider et d'afficher une spécification. Consultez [Transformez votre spécification avec des overlays](/fr/api-playground/openapi-setup#transform-your-spec-with-overlays).
+
## P
diff --git a/organize/settings-api.mdx b/organize/settings-api.mdx
index af4007e971..a28acf3994 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#transform-your-spec-with-overlays) documents to apply to the specification, in order. An empty array disables all overlays for the 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/docs-adjustments.yaml"]
+ }
+ ```
+
diff --git a/organize/settings-reference.mdx b/organize/settings-reference.mdx
index 1e4defea10..e01ebc5fc2 100644
--- a/organize/settings-reference.mdx
+++ b/organize/settings-reference.mdx
@@ -759,7 +759,7 @@ API documentation and playground settings.
OpenAPI specification files.
-**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`
diff --git a/reference/glossary.mdx b/reference/glossary.mdx
index 9da578ae68..072992e05b 100644
--- a/reference/glossary.mdx
+++ b/reference/glossary.mdx
@@ -174,6 +174,10 @@ A standard format for describing HTTP APIs. Mintlify can generate endpoint pages
A Mintlify workspace that contains team members, organization-level settings, shared credits, and one or more deployments.
+### Overlay
+
+A JSON or YAML document that describes changes to apply to an OpenAPI specification without editing its source file. Mintlify applies overlays before validating and rendering a specification. See [Transform your spec with overlays](/api-playground/openapi-setup#transform-your-spec-with-overlays).
+
## P
### Page
diff --git a/zh/api-playground/openapi-setup.mdx b/zh/api-playground/openapi-setup.mdx
index 92be66bd1b..4178de8e53 100644
--- a/zh/api-playground/openapi-setup.mdx
+++ b/zh/api-playground/openapi-setup.mdx
@@ -1,6 +1,6 @@
---
title: "OpenAPI 设置"
-description: "从 OpenAPI 3.0 和 3.1 规范文件生成交互式 API 文档，自动创建端点页面、请求构建器和导航结构，并配置身份验证、服务器 URL、请求参数与文件上传，帮助你快速发布完整且易于测试的 API 参考文档。了解如何设置规范文件、服务器地址、安全方案和文件字段。"
+description: "从 OpenAPI 3.0 和 3.1 规范文件生成交互式 API 文档，自动创建端点页面，并支持身份验证、服务器 URL 和 Overlay 配置。"
keywords: ["OpenAPI", "API 规范", "Swagger"]
---
@@ -202,6 +202,100 @@ API playground 会使用这些服务器 URL 来确定请求的发送目标。如
API playground 目前不支持从数组类型 schema 属性上的 `x-default` 进行预填，即使已启用 `api.examples.prefill` 也是如此。
+
+ ## 使用 Overlay 转换你的规范
+
+
+使用 [OpenAPI Overlay](https://spec.openapis.org/overlay/v1.1.0.html) 可以在不编辑源文件的情况下修改 OpenAPI 规范。Overlay 是独立的 JSON 或 YAML 文件，用于描述一组有序的更改；当规范由其他工具生成或由其他团队维护时，这非常有用。常见用途包括重命名路径、替换服务器 URL 以及移除内部端点。
+
+Overlay 会在解析规范之后、验证之前应用，因此生成的端点页面、导航、`openapi` frontmatter 引用以及 `mint validate` 都使用转换后的文档。支持 Overlay 规范的 1.0 和 1.1 版本。
+
+
+ ### 创建 Overlay 文档
+
+
+Overlay 文档包含一个 `overlay` 版本、一个带有 `title` 和 `version` 的 `info` 对象，以及一个 `actions` 数组。每个 action 使用 `target` [RFC 9535 JSONPath](https://www.rfc-editor.org/rfc/rfc9535) 表达式选择节点，并应用一个修改器：
+
+* `update`：将一个值合并到每个目标节点。对象会递归合并，数组会追加该值，基本类型会被替换。
+* `remove`：设置为 `true` 时删除每个目标节点。
+* `copy`：将另一个 JSONPath 表达式选中的节点复制到每个目标节点。需要 Overlay 1.1。
+
+```yaml docs-overlay.yaml
+overlay: 1.1.0
+info:
+ title: Docs adjustments
+ version: 1.0.0
+extends: ./openapi.json
+actions:
+ - target: $.info.description
+ update: "The public API for Example, Inc."
+ - target: $.paths['/internal-metrics']
+ remove: true
+```
+
+可选的 `extends` 字段将 Overlay 关联到某个规范，以便进行[自动发现](#auto-discover-overlays)。将其设置为相对于 Overlay 文件的路径，或设置为你的 `docs.json` 中托管规范所使用的确切 URL。
+
+
+ ### 在 docs.json 中引用 Overlay
+
+
+使用 `openapi` 字段的对象形式列出 Overlay，该形式可用于任何接受 `openapi` 的位置，包括数组内部。Overlay 会按照你列出的顺序应用。
+
+```json {6-9}
+"navigation": {
+ "tabs": [
+ {
+ "tab": "API reference",
+ "openapi": {
+ "source": "openapi.json",
+ "overlays": [
+ "overlays/rename-paths.yaml",
+ "https://example.com/overlays/servers.yaml"
+ ]
+ }
+ }
+ ]
+}
+```
+
+Overlay 路径必须指向文档仓库内的文件，Overlay URL 必须使用 `https`。在不同位置使用不同的 `overlays` 列表引用同一个规范会导致构建失败。
+
+
+ ### 自动发现 Overlay
+
+
+仓库中任何带有顶层 `overlay` 键的 JSON 或 YAML 文件都会被视为 Overlay 文档。如果其 `extends` 字段解析为你的某个规范，该 Overlay 会自动应用到该规范。自动发现的 Overlay 按其文件路径的字母顺序应用。没有 `extends` 字段的 Overlay 永远不会自动应用。
+
+显式的 `overlays` 列表会取代该规范的自动发现。设置 `"overlays": []` 可禁用该规范的所有 Overlay，包括自动发现的 Overlay。
+
+显式 Overlay 与自动发现的 Overlay 的失败方式不同。如果显式 Overlay 无法加载或应用，该规范将无法通过验证，部署会报告规范错误。如果自动发现的 Overlay 失败，则会跳过它并发布未应用该 Overlay 的规范。
+
+
+ ### 重命名路径
+
+
+Overlay 规范没有移动 (move) 操作。要重命名路径，请使用 `update` 创建新路径，使用 `copy` 将现有路径项复制到新路径中，然后使用 `remove` 删除旧路径。
+
+```yaml rename-overlay.yaml
+overlay: 1.1.0
+info:
+ title: Move accounts under credit
+ version: 1.0.0
+extends: ./openapi.json
+actions:
+ - target: $.paths
+ update:
+ /credit/accounts: {}
+ - target: $.paths['/credit/accounts']
+ copy: $.paths['/accounts']
+ - target: $.paths['/accounts']
+ remove: true
+```
+
+在文档中的所有位置都应引用转换后的规范。例如，页面 frontmatter 必须使用应用 Overlay 之后的路径：`openapi: "POST /credit/accounts"`。
+
+在 `mint dev` 中，编辑或删除 Overlay 文件会重新构建受影响的规范。`mint validate` 和 `mint openapi-check` 会验证转换后的文档，因此错误引用的是应用 Overlay 之后的规范。
+
## 让访客下载你的规范
diff --git a/zh/organize/settings-api.mdx b/zh/organize/settings-api.mdx
index a5a0325dbd..5ceebf34e3 100644
--- a/zh/organize/settings-api.mdx
+++ b/zh/organize/settings-api.mdx
@@ -15,7 +15,7 @@ keywords: ["api", "openapi", "asyncapi", "演练场", "docs.json", "api 参考"]
在 `api` 键下定义所有与 API 相关的设置。
- 用于生成 API 参考页面的 OpenAPI 规范文件。接受单个路径或 URL、路径和 URL 数组，或指定 source 和 directory 的对象。
+ 用于生成 API 参考页面的 OpenAPI 规范文件。接受单个路径或 URL、由路径、URL 和对象组成的数组，或指定 source、directory 和 overlays 的对象。
@@ -24,6 +24,9 @@ keywords: ["api", "openapi", "asyncapi", "演练场", "docs.json", "api 参考"]
搜索 OpenAPI 文件的目录。开头不要包含斜杠。
+
+ 要按顺序应用到该规范的 [OpenAPI Overlay](/zh/api-playground/openapi-setup#transform-your-spec-with-overlays) 文档的路径或 URL。空数组会禁用该规范的所有 Overlay，包括自动发现的 Overlay。
+
@@ -47,6 +50,13 @@ keywords: ["api", "openapi", "asyncapi", "演练场", "docs.json", "api 参考"]
}
```
+ ```json Overlays
+ "openapi": {
+ "source": "openapi.json",
+ "overlays": ["overlays/docs-adjustments.yaml"]
+ }
+ ```
+
diff --git a/zh/organize/settings-reference.mdx b/zh/organize/settings-reference.mdx
index 4378b6cb9d..53dca0090a 100644
--- a/zh/organize/settings-reference.mdx
+++ b/zh/organize/settings-reference.mdx
@@ -509,7 +509,7 @@ API 文档和演练场设置。
OpenAPI 规范文件。
-**类型：** string | string 数组 | 带有 `source` (string) 和 `directory` (string) 的 object
+**类型：** string | string 或 object 数组 | 带有 `source` (string)、`directory` (string) 和 `overlays` (string 数组) 的 object
#### `api.asyncapi`
diff --git a/zh/reference/glossary.mdx b/zh/reference/glossary.mdx
index c0629da33f..004652669b 100644
--- a/zh/reference/glossary.mdx
+++ b/zh/reference/glossary.mdx
@@ -270,6 +270,12 @@ Mintlify 与其他服务之间的连接。集成可提供分析、聊天、隐
Mintlify 工作区，包含团队成员、组织级设置、共享积分以及一个或多个部署。
+
+### Overlay
+
+
+一种 JSON 或 YAML 文档，用于描述要应用到 OpenAPI 规范的更改，而无需编辑其源文件。Mintlify 会在验证和渲染规范之前应用 Overlay。参阅 [使用 Overlay 转换你的规范](/zh/api-playground/openapi-setup#transform-your-spec-with-overlays)。
+
## P