`.
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.
### Especificar la URL de tu API
Para habilitar funciones de Mintlify como el área de pruebas de la API, agrega un campo `servers` a tu documento de OpenAPI con la URL base de tu API.
```json theme={null}
{
"servers": [
{
"url": "https://api.example.com/v1"
}
]
}
```
En un documento de OpenAPI, los distintos endpoints de la API se especifican por sus rutas, como `/users/{id}` o simplemente `/`. La URL base define dónde deben añadirse estas 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 utiliza estas URL de servidor para determinar adónde enviar las solicitudes. Si especificas varios servidores, un menú desplegable permitirá a los usuarios cambiar entre servidores. Si no especificas un servidor, el área de pruebas de la API usará el modo simple, ya que no puede enviar solicitudes sin una URL base.
Si tu API tiene endpoints que están en distintas URL, puedes [anular 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 área de pruebas de la API, configura los campos `securitySchemes` y `security` en tu documento de OpenAPI. Las descripciones de la API y el área de pruebas añadirán campos de autenticación según la configuración de seguridad de tu documento de OpenAPI.
Añade un campo `securitySchemes` para definir cómo se autentican los usuarios.
Este ejemplo muestra una configuración para autenticación de tipo bearer.
```json theme={null}
{
"components": {
"securitySchemes": {
"bearerAuth": {
"type": "http",
"scheme": "bearer"
}
}
}
}
```
Añade un campo `security` para requerir autenticación.
```json theme={null}
{
"security": [
{
"bearerAuth": []
}
]
}
```
Los tipos de autenticación más comunes incluyen:
* [API Keys](https://swagger.io/docs/specification/authentication/api-keys/): Para keys en encabezados, query o cookies.
* [Bearer](https://swagger.io/docs/specification/authentication/bearer-authentication/): Para tokens JWT (JSON Web Token) u OAuth.
* [Basic](https://swagger.io/docs/specification/authentication/basic-authentication/): Para nombre de usuario y contraseña.
Si distintos endpoints de tu API requieren métodos de autenticación diferentes, 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.
## Extensión `x-mint`
La extensión `x-mint` es una extensión personalizada de OpenAPI que ofrece mayor control sobre cómo se genera y se muestra la documentación de tu API.
### Metadata
Sobrescribe la metadata predeterminada de las páginas de API generadas agregando `x-mint: metadata` a cualquier operación. Puedes usar cualquier campo de metadata válido en el frontmatter de `MDX`, excepto `openapi`:
```json {7-13} theme={null}
{
"paths": {
"/users": {
"get": {
"summary": "Obtener usuarios",
"description": "Recuperar una lista de usuarios",
"x-mint": {
"metadata": {
"title": "Listar todos los usuarios",
"description": "Obtener datos de usuario paginados con opciones de filtrado",
"og:title": "Mostrar una lista de usuarios"
}
},
"parameters": [
{
// Configuración de parámetros
}
]
}
}
}
}
```
### Contenido
Agrega contenido antes de la documentación de la API generada automáticamente usando `x-mint: content`:
```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 limitación de velocidad.\n\nLos correos electrónicos de usuario deben ser únicos en todo el sistema."
},
"parameters": [
{
// Configuración de parámetros
}
]
}
}
}
}
```
La extensión `content` es compatible con todos los componentes y el formato de MDX de Mintlify.
### Href
Cambia la URL de la página del endpoint en tu documentación con `x-mint: href`:
```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"
}
}
}
}
}
```
Cuando `x-mint: href` está presente, la entrada de navigation enlazará directamente a la URL especificada en lugar de generar una página de la API.
### MCP
Expón selectivamente endpoints como herramientas de Model Context Protocol (MCP) usando `x-mint: mcp`. Habilita solo los endpoints que sean seguros para el acceso público a través de herramientas de IA.
La configuración de MCP para el endpoint.
Indica si se expone el endpoint como una herramienta MCP. Tiene prioridad sobre la configuración a nivel de archivo.
El nombre de la herramienta MCP.
La descripción de la herramienta MCP.
```json Selective enablement {6-9} wrap theme={null}
{
"paths": {
"/users": {
"post": {
"summary": "Create user",
"x-mint": {
"mcp": {
"enabled": true
},
// ...
}
}
},
"/users": {
"delete": {
"summary": "Delete user (admin only)",
// No `x-mint: mcp` so this endpoint is not exposed as an MCP tool
// ...
}
}
}
}
```
```json Global enablement {3-5, 9-13} wrap theme={null}
{
"openapi": "3.1.0",
"x-mcp": {
"enabled": true // All endpoints are exposed as MCP tools by default
},
"paths": {
"/api/admin/delete": {
"delete": {
"x-mint": {
"mcp": {
"enabled": false // Disable MCP for this endpoint
}
},
"summary": "Delete resources"
}
}
}
}
```
Para obtener más información, consulta [Model Context Protocol](/es/ai/model-context-protocol).
## Rellenar automáticamente páginas de API
Agrega un campo `openapi` a cualquier elemento de `navigation` 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 de archivo en tu repositorio de documentación o una URL a un documento de OpenAPI hospedado.
Las páginas de endpoints generadas tienen estos valores de metadata predeterminados:
* `title`: El campo `summary` de la operación, si está presente. Si no hay `summary`, el título se genera a partir del método HTTP y el endpoint.
* `description`: El campo `description` de la operación, si está presente.
* `version`: El valor de `version` del ancla o Tab principal, si está presente.
* `deprecated`: El campo `deprecated` de la operación. Si es `true`, aparecerá una etiqueta en desuso 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, agrega la
propiedad [x-hidden](/es/api-playground/customization/managing-page-visibility#x-hidden)
a la operación en tu especificación de OpenAPI.
Hay dos enfoques para agregar páginas de endpoints a tu documentación:
1. **Secciones de API dedicadas**: Haz referencia a especificaciones de OpenAPI en elementos de `navigation` para secciones de API dedicadas.
2. **Endpoints selectivos**: Haz referencia a endpoints específicos en tu navegación junto con otras páginas.
### Secciones de API dedicadas
Genera secciones de API dedicadas añadiendo un campo `openapi` a un elemento de navigation y sin agregar otras páginas. Se incluirán todos los endpoints de la especificación:
```json {5} theme={null}
"navigation": {
"tabs": [
{
"tab": "Referencia de API",
"openapi": "https://petstore3.swagger.io/api/v3/openapi.json"
}
]
}
```
Puedes utilizar varias especificaciones de OpenAPI en diferentes secciones de navigation:
```json {8-11, 15-18} theme={null}
"navigation": {
"tabs": [
{
"tab": "Referencia de API",
"groups": [
{
"group": "Usuarios",
"openapi": {
"source": "/path/to/openapi-1.json",
"directory": "api-reference"
}
},
{
"group": "Admin",
"openapi": {
"source": "/path/to/openapi-2.json",
"directory": "api-reference"
}
}
]
}
]
}
```
El campo `directory` es opcional y especifica dónde se almacenan 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 necesites más control sobre dónde aparecen los endpoints en tu documentación, puedes hacer referencia a endpoints específicos en tu navigation. Este enfoque te permite generar páginas para endpoints de la API junto con otros contenidos.
#### Configurar una especificación de OpenAPI predeterminada
Configura una especificación de OpenAPI predeterminada para un elemento de navigation. Luego, haz referencia a 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` generará una página de API para ese endpoint usando la especificación OpenAPI predeterminada.
#### Herencia de especificaciones de OpenAPI
Las especificaciones de OpenAPI se heredan a lo largo de la jerarquía de navigation. Los elementos secundarios de navigation heredan la especificación de OpenAPI de su elemento padre, 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
Hace referencia a endpoints específicos sin establecer una especificación de OpenAPI predeterminada, incluyendo la ruta del archivo:
```json {5-6} theme={null}
"navigation": {
"pages": [
"introduction",
"user-guides",
"/path/to/openapi-v1.json POST /users",
"/path/to/openapi-v2.json GET /orders"
]
}
```
Este enfoque es útil cuando necesitas endpoints individuales de distintas especificaciones o solo quieres incluir endpoints específicos.
## Crear archivos `MDX` para páginas de API
Para controlar páginas de endpoints individuales, crea páginas `MDX` para cada operación. Esto te permite personalizar la metadata de la página, agregar contenido, omitir ciertas operaciones o reordenar páginas en tu navigation a nivel de página.
Consulta un [ejemplo de página MDX de OpenAPI de MindsDB](https://github.com/mindsdb/mindsdb/blob/main/docs/rest/databases/create-databases.mdx?plain=1) y cómo aparece en su [documentación pública](https://docs.mindsdb.com/rest/databases/create-databases).
### Especificar archivos manualmente
Crea una página `MDX` para cada endpoint y especifica qué operación de OpenAPI mostrar usando el campo `openapi` en el frontmatter.
Cuando haces referencia a una operación de OpenAPI de esta forma, el nombre, la descripción, los parámetros, las respuestas y el área de pruebas de la API se generan automáticamente a partir de tu documento de OpenAPI.
Si tienes varios archivos de OpenAPI, incluye la ruta del archivo en tu referencia para asegurarte de que Mintlify encuentre el documento de OpenAPI correcto. Si solo tienes un archivo de OpenAPI, Mintlify lo detectará automáticamente.
Este enfoque funciona independientemente de si has establecido una especificación de OpenAPI predeterminada
en tu navigation. Puedes hacer referencia a cualquier endpoint de cualquier especificación de OpenAPI
si incluyes la ruta del archivo en el frontmatter.
Si quieres hacer referencia a un archivo de OpenAPI externo, agrega la URL del archivo a tu `docs.json`.
```mdx Example theme={null}
---
title: "Get users"
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: "title of the page"
description: "description of the page"
openapi: openapi-file-path method path
deprecated: boolean (not required)
version: "version-string" (not required)
---
```
El método y la ruta deben coincidir exactamente con la definición de tu
especificación de OpenAPI. Si el endpoint no existe en el archivo de OpenAPI,
la página quedará vacía.
### Autogenerar archivos `MDX`
Usa nuestro [scraper](https://www.npmjs.com/package/@mintlify/scraping) de Mintlify para autogenerar páginas `MDX` para documentos OpenAPI de gran tamaño.
Tu documento OpenAPI debe ser válido o no se generarán los archivos automáticamente.
El scraper genera:
* Una página `MDX` por cada operación en el campo `paths` de tu documento OpenAPI.
* Si tu documento OpenAPI es versión 3.1+, una página `MDX` por cada operación en el campo `webhooks` de tu documento OpenAPI.
* Un arreglo de entradas de navigation que puedes agregar a tu `docs.json`.
```bash theme={null}
npx @mintlify/scraping@latest openapi-file
```
```bash theme={null}
npx @mintlify/scraping@latest openapi-file -o api-reference
```
Agrega la opción `-o` para indicar la carpeta donde se crearán los archivos. Si no se especifica una carpeta, los archivos se crearán en el directorio de trabajo.
### Crear archivos `MDX` para esquemas de OpenAPI
Puedes crear páginas individuales para cualquier esquema de OpenAPI definido en el campo `components.schema` de un documento de OpenAPI:
```mdx Ejemplo theme={null}
---
openapi-schema: OrderItem
---
```
```mdx Formato theme={null}
---
openapi-schema: "schema-key"
---
```
Si tienes esquemas con el mismo nombre en varios archivos, también puedes especificar el archivo de OpenAPI:
```mdx Ejemplo theme={null}
---
openapi-schema: en-schema.json OrderItem
---
```
```mdx Formato theme={null}
---
openapi-schema: "path-to-schema-file schema-key"
---
```
## Webhooks
Los webhooks son devoluciones de llamada HTTP que tu API envía para notificar a sistemas externos cuando se producen eventos. Los webhooks son compatibles con documentos de OpenAPI 3.1+.
### Define webhooks en tu especificación de OpenAPI
Añade 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.
### Referencia de webhooks en archivos MDX
Al crear páginas MDX para webhooks, utiliza `webhook` en lugar de métodos HTTP como `GET` o `POST`:
```mdx theme={null}
---
title: "Webhook de ejemplo"
description: "Se activa cuando ocurre un evento"
openapi: "path/to/openapi-file webhook example-webhook-name"
---
```
El nombre del webhook debe coincidir exactamente con la key definida en el campo `webhooks` de tu especificación de OpenAPI.