`.
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.
## 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` ofrece un control adicional sobre cómo se genera y se muestra la documentación de tu API.
### 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-13} theme={null}
{
"paths": {
"/users": {
"get": {
"summary": "Obtener usuarios",
"description": "Obtener una lista de usuarios",
"x-mint": {
"metadata": {
"title": "Listar todos los usuarios",
"description": "Obtener datos de usuarios 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`. 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
Cambia la URL de la página del endpoint en tu documentación usando `x-mint: href`. Cuando `x-mint: href` está presente, la entrada de navegación enlaza directamente a la URL especificada en lugar de generar una página de la API.
```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"
}
}
}
}
}
```
## 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 de archivo en tu repositorio de documentación o una URL a un documento de OpenAPI alojado.
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`, 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 `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. Se incluyen 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"
}
]
}
```
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 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 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
Las especificaciones de OpenAPI se heredan a lo largo de la jerarquía de navegación. 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.
### Documentar 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: ruta-del-archivo-openapi método ruta
deprecated: boolean (opcional)
version: "cadena-de-versión" (opcional)
---
```
El método y la ruta deben coincidir exactamente con tu especificación de OpenAPI. Si tienes varias especificaciones de OpenAPI, incluye la ruta del archivo en la referencia. Las URL externas de OpenAPI pueden referenciarse 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 crearán 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 webhooks son compatibles en documentos de OpenAPI 3.1+.
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.