Update from code changes: document OpenAPI overlay support

api-playground/openapi-setup.mdx

@@ -187,6 +187,90 @@
 
 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`:
@@ -200,7 +284,7 @@
 When enabled, clicking the option downloads your OpenAPI spec directly. Deployments with multiple specs receive them bundled as `api-specs.zip`. On deployments behind `auth` or `userAuth`, only authenticated readers can download the spec.
 
 <Warning>
   The downloaded OpenAPI spec is unfiltered and does not respect [authentication groups](/deploy/authentication-setup). Any authenticated reader who can open the contextual menu receives the full spec, including endpoints and schemas that would otherwise be hidden from their group. Do not enable `download-spec` on an authenticated site if your OpenAPI spec contains endpoints or fields you consider sensitive.
 </Warning>
 
 ## Customize your endpoint pages
@@ -313,7 +397,7 @@
 
 ### Collapse playground fields
 
 Collapse object-type fields in the API playground by default using `x-mint: playground` with `expand: false` on any operation. Request sections like Authorization, Headers, Query, Path, and Body always stay expanded, and so does the top-level body object. Object fields nested within them start collapsed, so readers expand only the fields they want to interact with. If `expand` is not set, object fields are expanded by default.
 
 ```json {6-10}
 {

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.
 </Note>
 
+<div id="transform-your-spec-with-overlays">
+  ## Transforma tu especificación con overlays
+</div>
+
+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.
+
+<div id="create-an-overlay-document">
+  ### Crea un documento de overlay
+</div>
+
+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.
+
+<div id="reference-overlays-in-your-docsjson">
+  ### Haz referencia a los overlays en tu docs.json
+</div>
+
+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.
+
+<div id="auto-discover-overlays">
+  ### Descubrimiento automático de overlays
+</div>
+
+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.
+
+<div id="rename-a-path">
+  ### Renombrar una ruta
+</div>
+
+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.
+
 <div id="let-visitors-download-your-spec">
   ## Permite que los visitantes descarguen tu especificación
 </div>

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`.
 
 <ResponseField name="api.openapi" type="string or array or object">
-  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.
 
   <Expandable title="api.openapi object">
     <ResponseField name="source" type="string">
@@ -24,6 +24,9 @@ Define todos los ajustes relacionados con la API bajo la clave `api`.
     <ResponseField name="directory" type="string">
       Directorio donde buscar archivos OpenAPI. No incluyas una barra inicial.
     </ResponseField>
+    <ResponseField name="overlays" type="array of string">
+      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.
+    </ResponseField>
   </Expandable>
 
   <CodeGroup>
@@ -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"]
+  }
+  ```
+
   </CodeGroup>
 </ResponseField>
 

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`
 

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.
 
+<div id="overlay">
+### Overlay
+</div>
+
+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).
+
 <div id="p">
 ## P
 </div>

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é.
 </Note>
 
+<div id="transform-your-spec-with-overlays">
+  ## Transformez votre spécification avec des overlays
+</div>
+
+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.
+
+<div id="create-an-overlay-document">
+  ### Créer un document d’overlay
+</div>
+
+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.
+
+<div id="reference-overlays-in-your-docsjson">
+  ### Référencer les overlays dans votre docs.json
+</div>
+
+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.
+
+<div id="auto-discover-overlays">
+  ### Découverte automatique des overlays
+</div>
+
+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.
+
+<div id="rename-a-path">
+  ### Renommer un chemin
+</div>
+
+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.
+
 <div id="let-visitors-download-your-spec">
   ## Permettez aux visiteurs de télécharger votre spécification
 </div>