> ## Documentation Index
> Fetch the complete documentation index at: https://adminroletesting-justin-client-exports.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.
# Configuración de OpenAPI
> Genera documentación de API interactiva desde archivos OpenAPI con páginas de endpoints, constructores de solicitudes y navegación automáticos.
OpenAPI es una especificación para describir APIs. Mintlify es compatible con documentos OpenAPI 3.0 y 3.1 para generar documentación de API interactiva y mantenerla actualizada.
## Agrega un archivo de especificación OpenAPI
Para documentar tus endpoints con OpenAPI, necesitas una o más especificaciones OpenAPI válidas en formato JSON o YAML que sigan la [especificación OpenAPI 3.0 o 3.1](https://swagger.io/specification/).
Agrega especificaciones OpenAPI a tu repositorio de documentación o alójalas en línea donde puedas acceder a ellas mediante una URL. Las especificaciones almacenadas en tu repositorio se [sirven como archivos descargables](/es/create/files) en la ruta correspondiente de tu dominio de documentación. Por ejemplo, `https://your-domain/docs/openapi.json`.
Haz referencia a cualquier número de especificaciones OpenAPI en el elemento de navigation de tu `docs.json` para crear páginas para los endpoints de tu API. Cada archivo de especificación genera su propio conjunto de endpoints.
```json Single specification theme={null}
"navigation": {
"tabs": [
{
"tab": "API Reference",
"openapi": "openapi.json"
}
]
}
```
```json Multiple specifications theme={null}
"navigation": {
"tabs": [
{
"tab": "API Reference",
"openapi": [
"openapi/v1.json",
"openapi/v2.json"
]
}
]
}
```
Mintlify admite `$ref` para **referencias internas únicamente** dentro de un solo documento OpenAPI. No se admiten referencias externas.
### Describe tu API
Recomendamos los siguientes recursos para aprender y elaborar tu especificación de OpenAPI.
* [Guía de OpenAPI de Swagger](https://swagger.io/docs/specification/v3_0/basic-structure/) para aprender la sintaxis de OpenAPI.
* [Fuentes Markdown de la especificación OpenAPI](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/) para consultar los detalles de la versión más reciente de la especificación.
* [Swagger Editor](https://editor.swagger.io/) para editar, validar y depurar tu documento de OpenAPI.
* [La CLI de Mint](https://www.npmjs.com/package/mint) para validar tu documento de OpenAPI con el comando: `mint validate`.
La Guía de OpenAPI de Swagger corresponde a OpenAPI v3.0, pero casi toda la información es aplicable a v3.1. Para obtener más información sobre las diferencias entre v3.0 y v3.1, consulta [Migrating from OpenAPI 3.0 to 3.1.0](https://www.openapis.org/blog/2021/02/16/migrating-from-openapi-3-0-to-3-1-0) en el blog de OpenAPI.
### Especifica la URL base de tu API
Para habilitar el área de pruebas de la API, añade un campo `servers` a tu especificación de OpenAPI con la URL base de tu API.
```json theme={null}
{
"servers": [
{
"url": "https://api.example.com/v1"
}
]
}
```
En una especificación de OpenAPI, los distintos endpoints de la API se definen por sus rutas, como `/users/{id}` o simplemente `/`. La URL base indica dónde se deben anexar esas rutas. Para obtener más información sobre cómo configurar el campo `servers`, consulta [API Server and Base Path](https://swagger.io/docs/specification/api-host-and-base-path/) en la documentación de OpenAPI.
El área de pruebas de la API usa estas URL de servidor para determinar adónde enviar las solicitudes. Si especificas varios servidores, un menú desplegable permite a los usuarios alternar entre ellos. Si no especificas un servidor, el área de pruebas de la API utiliza el modo simple, ya que no puede enviar solicitudes sin una URL base.
Si tu API tiene endpoints que se encuentran en distintas URL, puedes [sobrescribir el campo `servers`](https://swagger.io/docs/specification/v3_0/api-host-and-base-path/#overriding-servers) para una ruta u operación determinada.
### Especificar la autenticación
Para habilitar la autenticación en la documentación y el playground de tu API, configura los campos `securitySchemes` y `security` en tu especificación de OpenAPI. Las descripciones de la API y el playground de la API agregan campos de autenticación basados en la configuración de seguridad de tu especificación de OpenAPI.
Agrega el campo `securitySchemes` para definir cómo se autentican los usuarios.
Este ejemplo muestra una configuración de autenticación Bearer.
```json theme={null}
{
"components": {
"securitySchemes": {
"bearerAuth": {
"type": "http",
"scheme": "bearer"
}
}
}
}
```
Agrega el campo `security` para requerir autenticación.
```json theme={null}
{
"security": [
{
"bearerAuth": []
}
]
}
```
Los tipos de autenticación más comunes incluyen:
* [Claves de API](https://swagger.io/docs/specification/authentication/api-keys/): Para claves en encabezado, consulta o cookie.
* [Bearer](https://swagger.io/docs/specification/authentication/bearer-authentication/): Para tokens JWT u OAuth.
* [Básica](https://swagger.io/docs/specification/authentication/basic-authentication/): Para usuario y contraseña.
Si distintos endpoints de tu API requieren diferentes métodos de autenticación, puedes [anular el campo `security`](https://swagger.io/docs/specification/authentication/#:~:text=you%20can%20apply%20them%20to%20the%20whole%20API%20or%20individual%20operations%20by%20adding%20the%20security%20section%20on%20the%20root%20level%20or%20operation%20level%2C%20respectively.) para una operación determinada.
Para obtener más información sobre cómo definir y aplicar la autenticación, consulta [Authentication](https://swagger.io/docs/specification/authentication/) en la documentación de OpenAPI.
#### Establecer valores predeterminados para esquemas de seguridad
Usa la extensión `x-default` en un esquema de seguridad para rellenar previamente el campo de autenticación en el playground de la API. Esto es útil para proporcionar valores de ejemplo o credenciales de prueba que ayuden a los usuarios a comenzar rápidamente.
```json {6} theme={null}
{
"components": {
"securitySchemes": {
"apiKey": {
"type": "apiKey",
"in": "header",
"name": "X-API-Key",
"x-default": "your-api-key-here"
}
}
}
}
```
La extensión `x-default` admite los tipos de esquema de seguridad `apiKey` y `http` bearer. El valor aparece como la entrada predeterminada en los campos de autenticación del playground.
También puedes usar `x-default` en cualquier propiedad de esquema en tu especificación de OpenAPI para establecer un valor predeterminado en el playground de la API sin afectar el campo `default` en la definición del esquema.
## Permite que los visitantes descarguen tu especificación
Habilita una entrada "Descargar especificación de API" en el [menú contextual de la página](/es/organize/settings-structure#contextual) añadiendo `"download-spec"` a `contextual.options` en tu `docs.json`:
```json theme={null}
"contextual": {
"options": ["copy", "download-spec", "chatgpt", "claude"]
}
```
Cuando está habilitada, al hacer clic en la opción se descarga directamente tu especificación de OpenAPI. Los despliegues con varias especificaciones las reciben empaquetadas como `api-specs.zip`. La opción se oculta en los despliegues protegidos por `auth` o `userAuth` para evitar filtrar el contenido de las especificaciones desde documentación autenticada.
## Personaliza las páginas de tus endpoints
Personaliza las páginas de tus endpoints añadiendo la extensión `x-mint` a tu especificación de OpenAPI. La extensión `x-mint` te ofrece un control adicional sobre cómo tu documentación de API se genera y se presenta.
### Metadatos
Sobrescribe los metadatos predeterminados de las páginas de API generadas añadiendo `x-mint: metadata` a cualquier operación. Puedes usar cualquier campo de metadatos válido en el frontmatter de MDX, excepto `openapi`.
```json {7-14} theme={null}
{
"paths": {
"/users": {
"get": {
"summary": "Get users",
"description": "Retrieve a list of users",
"x-mint": {
"metadata": {
"title": "List all users",
"sidebarTitle": "List users",
"description": "Obtener datos de usuarios paginados con opciones de filtrado",
"og:title": "Display a list of users"
}
},
"parameters": [
{
// Parameter configuration
}
]
}
}
}
}
```
También puedes controlar cómo se muestra el playground para cada endpoint usando los campos de metadata `playground` y `groups`:
```json {7-11} theme={null}
{
"paths": {
"/admin/users": {
"post": {
"summary": "Crear usuario administrador",
"x-mint": {
"metadata": {
"playground": "auth",
"groups": ["admin"],
"public": true
}
}
}
}
}
}
```
Esta configuración hace que la página sea pública mientras restringe el playground interactivo a usuarios autenticados del grupo `admin`.
### Contenido
Agrega contenido antes de la documentación de la API generada automáticamente usando `x-mint: content`. La extensión `x-mint: content` es compatible con todos los componentes y el formato MDX de Mintlify.
```json {6-8} theme={null}
{
"paths": {
"/users": {
"post": {
"summary": "Crear usuario",
"x-mint": {
"content": "## Requisitos previos\n\nEste endpoint requiere privilegios de administrador y tiene límite de tasa.\n\nLos correos electrónicos de los usuarios deben ser únicos en todo el sistema."
},
"parameters": [
{
// Configuración de parámetros
}
]
}
}
}
}
```
### href
Establece la URL de la página del endpoint generada automáticamente usando `x-mint: href`. Cuando `x-mint: href` está presente, la página de la API generada utiliza la URL especificada en lugar de la URL predeterminada generada automáticamente.
```json {6-8, 14-16} theme={null}
{
"paths": {
"/legacy-endpoint": {
"get": {
"summary": "Endpoint heredado",
"x-mint": {
"href": "/deprecated-endpoints/legacy-endpoint"
}
}
},
"/documented-elsewhere": {
"post": {
"summary": "Endpoint especial",
"x-mint": {
"href": "/guides/special-endpoint-guide"
}
}
}
}
}
```
### Píldoras de parámetro
Anota los parámetros en la referencia de la API y en el playground con etiquetas de píldora personalizadas usando `x-mint.pre` y `x-mint.post` en cualquier esquema. Las píldoras pre se renderizan antes del nombre del parámetro y las píldoras post se renderizan después, junto con las píldoras integradas de Mintlify como `required`, `read-only` y `write-only`.
Ambos campos aceptan un arreglo de cadenas. Cada cadena se convierte en su propia píldora.
```json {7-10} theme={null}
{
"components": {
"schemas": {
"User": {
"properties": {
"email": {
"type": "string",
"x-mint": {
"pre": ["PII"],
"post": ["indexed", "unique"]
}
}
}
}
}
}
}
```
Para mostrar campos arbitrarios de la especificación OpenAPI como píldoras en cada parámetro sin editar cada esquema, configura [`api.params.post`](/es/organize/settings-api#api-params) en tu `docs.json`. Enumera las claves de los campos que quieres mostrar y Mintlify lee cada valor del esquema y renderiza las píldoras correspondientes automáticamente.
```json theme={null}
{
"api": {
"params": {
"post": ["nullable", "x-internal"]
}
}
}
```
Con esta configuración, una propiedad como `{ "type": "string", "nullable": true, "x-internal": "admin" }` renderiza las píldoras `nullable` y `admin` junto a su nombre. Las píldoras post aparecen en este orden: píldoras integradas (`read-only`, `write-only`), luego las píldoras impulsadas por la configuración `api.params.post` y, por último, las píldoras `x-mint.post` por propiedad.
### Nombres de visualización de grupo
Establece un nombre de visualización personalizado para el grupo de navegación de un tag usando la extensión `x-group` en un objeto de tag. De forma predeterminada, Mintlify usa el `name` del tag tanto como etiqueta del grupo de navegación como segmento de la ruta URL. La extensión `x-group` sobrescribe la etiqueta del grupo mientras mantiene el nombre del tag para la URL.
Esto es útil cuando deseas un nombre de grupo legible que difiera del tag usado en las rutas de tu API.
```json {4-9} theme={null}
{
"tags": [
{
"name": "user-management",
"description": "Endpoints for managing users",
"x-group": "User Management"
}
],
"paths": {
"/users": {
"get": {
"tags": ["user-management"],
"summary": "List users"
}
}
}
}
```
En este ejemplo, el grupo de navegación se muestra como "User Management", pero la URL de la página generada sigue usando el nombre del tag `user-management` como segmento de la ruta.
## Generar automáticamente páginas de API
Añade un campo `openapi` a cualquier elemento de navegación en tu `docs.json` para generar automáticamente páginas para endpoints de OpenAPI. Puedes controlar dónde aparecen estas páginas en tu estructura de navegación, ya sea como secciones de API dedicadas o junto con otras páginas.
El campo `openapi` acepta una ruta en tu repositorio de documentación o una URL a un documento OpenAPI alojado.
Cuando usas una URL para tu especificación OpenAPI, los cambios en la especificación no generan un push a Git, por lo que tus docs no se redespliegan automáticamente. Para mantener tus docs sincronizados, llama al endpoint de API [Trigger deployment](/es/api/update/trigger) en la misma acción de CI que genera o actualiza tu especificación. De esta forma, tus docs se actualizan automáticamente sin necesidad de activar manualmente un despliegue desde el dashboard.
Las páginas de endpoints generadas tienen estos metadatos predeterminados:
* `title`: El campo `summary` de la operación, si está presente. Si no hay `summary`, Mintlify genera el título a partir del método HTTP y el endpoint.
* `description`: El campo `description` de la operación, si está presente.
* `version`: El valor `version` del ancla o pestaña principal, si está presente.
* `deprecated`: El campo `deprecated` de la operación. Si es `true`, aparece una etiqueta de “deprecated” junto al título del endpoint en la navegación lateral y en la página del endpoint.
Para excluir endpoints específicos de tus páginas de API generadas automáticamente, añade la propiedad [x-hidden](/es/api-playground/managing-page-visibility#x-hidden) a la operación en tu especificación de OpenAPI.
Hay dos enfoques para añadir páginas de endpoints a tu documentación:
1. **Secciones de API dedicadas**: Referencia especificaciones de OpenAPI en elementos de navegación para crear secciones de API dedicadas.
2. **Endpoints selectivos**: Referencia endpoints específicos en tu navegación junto con otras páginas.
### Secciones de API dedicadas
Crea secciones de API dedicadas añadiendo un campo `openapi` a un elemento de navegación y ninguna otra página. Todos los endpoints de la especificación aparecen en la sección generada.
```json {5} theme={null}
"navigation": {
"tabs": [
{
"tab": "Referencia de API",
"openapi": "https://petstore3.swagger.io/api/v3/openapi.json"
}
]
}
```
Para organizar varias especificaciones de OpenAPI en secciones separadas de tu documentación, asigna cada especificación a un grupo distinto dentro de la jerarquía de navegación. Cada grupo puede referenciar su propia especificación de OpenAPI.
```json {8-11, 15-18} theme={null}
"navigation": {
"tabs": [
{
"tab": "Referencia de API",
"groups": [
{
"group": "API de Usuarios",
"openapi": {
"source": "/path/to/users-openapi.json",
"directory": "users-api-reference"
}
},
{
"group": "API de Administrador",
"openapi": {
"source": "/path/to/admin-openapi.json",
"directory": "admin-api-reference"
}
}
]
}
]
}
```
El campo `directory` es opcional y especifica dónde Mintlify almacena las páginas de API generadas en tu repositorio de documentación. Si no se especifica, de forma predeterminada se usa el directorio `api-reference` de tu repositorio.
### Endpoints selectivos
Cuando quieras tener más control sobre dónde aparecen los endpoints en tu documentación, puedes hacer referencia a endpoints específicos en la navegación. Este enfoque te permite generar páginas de endpoints de API junto con otros contenidos. También puedes usarlo para combinar endpoints de diferentes especificaciones de OpenAPI.
#### Establecer una especificación de OpenAPI predeterminada
Configura una especificación de OpenAPI predeterminada para un elemento de navegación. Luego, referencia endpoints específicos en el campo `pages`.
```json {12, 15-16} theme={null}
"navigation": {
"tabs": [
{
"tab": "Primeros pasos",
"pages": [
"quickstart",
"installation"
]
},
{
"tab": "Referencia de API",
"openapi": "/path/to/openapi.json",
"pages": [
"api-overview",
"GET /users",
"POST /users",
"guides/authentication"
]
}
]
}
```
Cualquier entrada de página que coincida con el formato `METHOD /path` genera una página de API para ese endpoint utilizando la especificación predeterminada de OpenAPI.
#### Herencia de especificaciones de OpenAPI
Los elementos de navegación secundarios heredan la especificación de OpenAPI de su elemento principal, a menos que definan la suya propia.
```json {3, 7-8, 11, 13-14} theme={null}
{
"group": "Referencia de API",
"openapi": "/path/to/openapi-v1.json",
"pages": [
"overview",
"authentication",
"GET /users",
"POST /users",
{
"group": "Pedidos",
"openapi": "/path/to/openapi-v2.json",
"pages": [
"GET /orders",
"POST /orders"
]
}
]
}
```
#### Endpoints individuales
Haz referencia a endpoints específicos sin establecer una especificación de OpenAPI predeterminada, incluyendo la ruta del archivo. Puedes referenciar endpoints de múltiples especificaciones de OpenAPI en la misma sección de la documentación.
```json {5-6} theme={null}
"navigation": {
"pages": [
"introduccion",
"guias-de-usuario",
"/path/to/users-openapi.json POST /users",
"/path/to/orders-openapi.json GET /orders"
]
}
```
Este enfoque es útil cuando necesitas endpoints individuales de distintas especificaciones, solo quieres incluir algunos endpoints o prefieres incluir endpoints junto con otros tipos de documentación.
## Crea páginas MDX a partir de tu especificación de OpenAPI
Para tener un control más granular de las páginas de endpoints individuales, crea páginas MDX a partir de tu especificación de OpenAPI. Esto te permite personalizar los metadatos y el contenido de la página, además de reordenar o excluir páginas en la navegación, mientras sigues utilizando los parámetros y respuestas generados automáticamente.
Hay dos formas de documentar tu especificación de OpenAPI con páginas MDX individuales:
* Documenta los endpoints con el campo `openapi` en el frontmatter.
* Documenta los modelos de datos con el campo `openapi-schema` en el frontmatter.
### Document endpoints
Crea una página para cada endpoint y especifica qué operación de OpenAPI mostrar usando el campo `openapi` en el frontmatter.
```mdx Example theme={null}
---
title: "Obtener usuarios"
description: "Devuelve todas las plantas del sistema a las que el usuario tiene acceso"
openapi: "/path/to/openapi-1.json GET /users"
deprecated: true
version: "1.0"
---
```
```mdx Format theme={null}
---
title: "título de la página"
description: "descripción de la página"
openapi: openapi-file-path method path
deprecated: boolean (no requerido)
version: "cadena-de-versión" (no requerido)
---
```
El método y la ruta deben coincidir exactamente con tu especificación de OpenAPI. Si tienes varias especificaciones de OpenAPI, incluye la ruta a la especificación correcta en tu referencia. También puedes hacer referencia a URLs externas de OpenAPI en `docs.json`.
#### Generar automáticamente páginas de endpoints
Para generar automáticamente archivos MDX a partir de tu especificación de OpenAPI, usa el [scraper](https://www.npmjs.com/package/@mintlify/scraping) de Mintlify.
```bash theme={null}
npx @mintlify/scraping@latest openapi-file -o
```
Agrega la opción `-o` para especificar una carpeta donde se crearán los archivos. Si no se especifica una carpeta, los archivos se crean en el directorio de trabajo.
### Documentar modelos de datos
Crea una página para cada estructura de datos definida en `components.schemas` de tu especificación de OpenAPI usando el campo `openapi-schema` en el frontmatter.
```mdx Example theme={null}
---
openapi-schema: OrderItem
---
```
```mdx Format theme={null}
---
openapi-schema: "openapi-file-path schema-key"
---
```
Si tienes esquemas con el mismo nombre en varios archivos, especifica el archivo de OpenAPI:
```mdx Example theme={null}
---
openapi-schema: en-schema.json OrderItem
---
```
```mdx Format theme={null}
---
openapi-schema: "path-to-schema-file schema-key"
---
```
## Webhooks
Los webhooks son devoluciones de llamada (callbacks) HTTP que tu API envía para notificar a sistemas externos cuando se producen eventos. Los documentos de OpenAPI 3.1+ admiten webhooks.
Agrega un campo `webhooks` a tu documento de OpenAPI junto con el campo `paths`.
Para obtener más información sobre cómo definir webhooks, consulta [Webhooks](https://spec.openapis.org/oas/v3.1.0#oasWebhooks) en la documentación de OpenAPI.
Para crear una página MDX para un webhook (OpenAPI 3.1+), usa `webhook` en lugar de un método HTTP:
```mdx theme={null}
---
title: "Webhook de pedido actualizado"
description: "Se activa cuando se actualiza un pedido"
openapi: "openapi.json webhook orderUpdated"
---
```
El nombre del webhook debe coincidir exactamente con la clave en el campo `webhooks` de tu especificación de OpenAPI.
## Callbacks
Los callbacks describen solicitudes fuera de banda que tu API envía a una URL proporcionada por quien la llama, como notificaciones de eventos vinculadas a una operación específica. Cuando una operación de OpenAPI define `callbacks`, Mintlify los muestra en la página del endpoint en una sección plegable entre el cuerpo de la solicitud y la sección de respuesta. Cada callback muestra su método HTTP, su expresión y reutiliza los mismos componentes de cuerpo y respuesta que la operación principal.
No necesitas configurar nada para mostrar los callbacks. Si tu especificación de OpenAPI define `callbacks` en una operación, aparecerán automáticamente en la página del endpoint generada.
Para obtener más información sobre cómo definir callbacks, consulta [Callbacks](https://spec.openapis.org/oas/v3.1.0#callback-object) en la documentación de OpenAPI.
Ejemplo de definición de callback en una operación:
```yaml theme={null}
paths:
/subscribe:
post:
summary: Suscribirse a eventos
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
callbackUrl:
type: string
format: uri
responses:
"201":
description: Suscripción creada
callbacks:
orderUpdated:
"{$request.body#/callbackUrl}":
post:
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
orderId:
type: string
status:
type: string
responses:
"200":
description: Callback recibido
```