Mintlify transforma especificaciones OpenAPI 3.0 y 3.1 (en formato JSON o YAML) en documentación de API interactiva y moderna. En lugar de redactar y mantener manualmente tablas de parámetros, encabezados de solicitud y esquemas de respuesta, los equipos de desarrollo y redacción técnica pueden importar su definición OpenAPI directamente. Mintlify se encarga de analizar los puntos de conexión, generar ejemplos de código en múltiples lenguajes de programación y proporcionar una consola de pruebas (Playground) donde los desarrolladores pueden ejecutar solicitudes en tiempo real desde el navegador.
La arquitectura de la plataforma sigue el modelo de documentación como código (Docs-as-code). El archivo OpenAPI se almacena junto al contenido Markdown en Git, gobernado por un archivo central de configuración (docs.json, o mint.json en proyectos previos). Los equipos pueden optar por dos enfoques: una generación totalmente automatizada sin mantenimiento manual a partir de la especificación, o la vinculación precisa de rutas OpenAPI a páginas MDX personalizadas para integrar tutoriales, advertencias operativas y explicaciones conceptuales.
Requisitos previos y compatibilidad de especificaciones
Antes de iniciar la configuración en Mintlify, verifique que su documento cumpla con los estándares requeridos:
- Versiones admitidas: Mintlify ofrece soporte nativo para OpenAPI Specification (OAS) 3.0 y 3.1. Si su archivo utiliza la especificación Swagger 2.0, debe migrarlo a OpenAPI 3.0 antes de la importación.
- Formatos de archivo: Se admiten archivos estándar en JSON (
.json) y YAML (.yamlo.yml). - Restricciones de referencias ($ref): Mintlify resuelve sin inconvenientes las referencias internas dentro de un mismo documento (por ejemplo,
$ref: '#/components/schemas/User'). Sin embargo, no admite referencias externas divididas en múltiples archivos. Si su especificación se encuentra fragmentada en distintos esquemas externos, debe consolidarla en un único archivo (utilizando herramientas como Redocly CLI o@apidevtools/swagger-cli) antes de integrarla.
Paso 1: Ubicación del archivo de especificación OpenAPI
Puede vincular su archivo OpenAPI mediante almacenamiento local en el repositorio o a través de una URL remota:
-
Repositorio local (Opción recomendada): Guarde el archivo de especificación directamente en su repositorio de documentación. La convención habitual es situarlo en la raíz del proyecto (por ejemplo,
openapi.jsonoopenapi.yaml) o dentro de un directorio dedicado (comoapi-reference/openapi.jsonospecs/v1.yaml). -
URL remota alojada: Si sus canalizaciones de CI/CD publican automáticamente la especificación actualizada en un bucket de almacenamiento o CDN, puede configurar un enlace HTTPS directo (por ejemplo,
https://api.example.com/specs/openapi.json). Para compilaciones en entornos de producción, las especificaciones remotas deben servirse obligatoriamente mediante HTTPS.
Paso 2: Configuración de la navegación en docs.json
Para que la sección de referencia de API aparezca en la barra lateral de su sitio, debe declararla en el bloque navigation de su archivo docs.json.
Enfoque A: Generación automática completa
Si desea que Mintlify procese automáticamente todas las rutas, las clasifique según las etiquetas (tags) de OpenAPI y construya las páginas de documentación sin redactar archivos individuales, declare el archivo en una pestaña o grupo de navegación:
{
"$schema": "https://mintlify.com/docs.json",
"name": "Acme API Docs",
"navigation": {
"tabs": [
{
"tab": "Guías",
"groups": [
{
"group": "Primeros pasos",
"pages": ["introduction", "quickstart"]
}
]
},
{
"tab": "API Reference",
"openapi": "openapi.json"
}
]
}
}
Bajo este esquema, Mintlify examina todos los métodos declarados en paths, extrae descripciones, parámetros y esquemas de respuesta, y genera una jerarquía navegable sin necesidad de un solo archivo MDX.
Gestión de múltiples especificaciones
Cuando la arquitectura se compone de distintos microservicios o versiones de API diferenciadas, puede declarar un arreglo de rutas de archivo:
{
"navigation": {
"tabs": [
{
"tab": "API Reference",
"openapi": [
"specs/v1/auth.json",
"specs/v1/billing.json",
"specs/v2/core.json"
]
}
]
}
}
Paso 3: Control granular mediante páginas MDX
Aunque la automatización total ahorra tiempo, los redactores técnicos a menudo requieren enriquecer las operaciones clave con diagramas de secuencia, requisitos de permisos, límites de tasa o advertencias de seguridad. Mintlify permite vincular páginas MDX a operaciones OpenAPI específicas mediante el Frontmatter.
1. Enlazar un archivo MDX a un punto de conexión
Cree un archivo MDX (por ejemplo, api-reference/users/create.mdx) e indique el método HTTP y la ruta en el campo openapi:
---
title: "Crear usuario"
sidebarTitle: "Crear usuario"
description: "Registra una nueva cuenta de usuario dentro de la organización"
openapi: "POST /v1/users"
---
## Requisitos previos
Antes de invocar este endpoint, confirme que la aplicación cliente cuenta con el ámbito OAuth `users:write`.
<Warning>
La dirección de correo electrónico debe ser única en toda la organización. Intentar registrar un correo existente devolverá un error `409 Conflict`.
</Warning>
## Notificaciones por Webhook
Tras completarse el registro, el sistema emitirá de forma automática el evento `user.created` hacia los puntos de conexión configurados.
Al compilar la página, Mintlify toma los parámetros y la consola de pruebas de POST /v1/users y los inserta de manera nativa alrededor de su contenido MDX.
Si utiliza múltiples archivos OpenAPI en el mismo proyecto, anteponga la ruta del archivo correspondiente para evitar ambigüedades:
---
title: "Crear usuario"
openapi: "specs/v1/auth.json POST /v1/users"
---
2. Generación en lote de archivos MDX con la utilidad oficial
Si dispone de decenas de endpoints y desea contar con archivos base listos para editar, ejecute la herramienta de extracción de Mintlify:
npx @mintlify/scraping@latest openapi-file ./openapi.json -o api-reference
El script analizará su especificación y creará la estructura completa de archivos MDX dentro del directorio api-reference con sus respectivos campos de Frontmatter preconfigurados.
Paso 4: Configuración de la consola de pruebas interactiva (Playground)
El entorno interactivo de Mintlify permite a los desarrolladores enviar llamadas reales contra el servidor API. Para optimizar el funcionamiento de la consola, ajuste los siguientes elementos:
1. Definición de la URL base del servidor
Mintlify toma las URLs de destino directamente de la matriz servers definida en la especificación:
servers:
- url: https://api.example.com/v1
description: Servidor de Producción
- url: https://staging.api.example.com/v1
description: Entorno Sandbox de Pruebas
Si define varios entornos, la consola presentará un selector desplegable para que el usuario escoja el destino de sus pruebas.
2. Esquemas de autenticación y credenciales de prueba
Declare la estructura de credenciales en components.securitySchemes. Mintlify generará automáticamente los campos de entrada correspondientes (Bearer Token, API Key, Basic Auth, etc.):
components:
securitySchemes:
bearerAuth:
type: http
scheme: bearer
bearerFormat: JWT
description: Ingrese su token de acceso a la API
security:
- bearerAuth: []
Para acelerar las pruebas en entornos de prueba públicos, puede preconfigurar claves de demostración seguras usando la extensión x-default:
{
"components": {
"securitySchemes": {
"apiKey": {
"type": "apiKey",
"in": "header",
"name": "X-API-Key",
"x-default": "demo_pk_live_testing123"
}
}
}
}
3. Soporte de CORS (Cross-Origin Resource Sharing)
Dado que las llamadas de la consola se emiten directamente desde el navegador del lector, el servidor receptor debe responder adecuadamente a las solicitudes de origen cruzado:
Access-Control-Allow-Origin: *(o el dominio exacto de su documentación)Access-Control-Allow-Methods: GET, POST, PUT, DELETE, PATCH, OPTIONSAccess-Control-Allow-Headers: Authorization, Content-Type, X-API-Key
Si el backend rechaza las solicitudes previas de verificación (OPTIONS), la consola interactiva fallará por bloqueo del navegador, a pesar de que las pruebas mediante curl funcionen localmente.
Paso 5: Ajuste de especificaciones con OpenAPI Overlays
En muchos proyectos, las especificaciones exportadas automáticamente por el backend contienen rutas internas o descripciones poco amigables para el usuario. Para evitar la edición directa de archivos generados o el mantenimiento de bifurcaciones, Mintlify admite la especificación OpenAPI Overlay (v1.1.0).
Un archivo de superposición aplica modificaciones no destructivas mediante expresiones JSONPath (update, remove, copy):
overlay: 1.1.0
info:
title: Ajustes de documentación pública
version: 1.0.0
extends: ./openapi.json
actions:
- target: $.info.description
update: "Bienvenido a la documentación oficial para desarrolladores de Acme. Pruebe nuestros endpoints en tiempo real."
- target: $.paths['/internal/system-health']
remove: true
- target: $.paths['/v1/billing'].post.summary
update: "Crear suscripción de facturación periódica"
Luego, enlace el archivo de superposición en su docs.json:
{
"navigation": {
"tabs": [
{
"tab": "API Reference",
"openapi": {
"source": "openapi.json",
"overlays": ["overlays/public-filter.yaml"]
}
}
]
}
}
Mintlify aplica las transformaciones durante la compilación, ocultando rutas internas y puliendo los textos sin alterar la especificación original generada por los ingenieros.
Paso 6: Validación local y automatización CI/CD
Antes de publicar los cambios, use la interfaz de línea de comandos de Mintlify para comprobar la integridad del proyecto:
-
Iniciar el servidor local de desarrollo:
npm i -g mintlify mint dev -
Probar especificaciones locales en tiempo de ejecución: Si su especificación se sirve desde un puerto local (como
http://localhost:8000/openapi.json), ejecute el comando con permisos de red local:mint dev --local-schema -
Ejecutar validación de esquemas: Detecte referencias rotas o inconsistencias estructurales con:
mint validate -
Automatización en CI/CD: Integre
mint validateen sus flujos de trabajo de GitHub Actions o GitLab CI. Cada vez que el equipo de backend actualice la definición OpenAPI, la canalización comprobará la validez estructural y evitará publicaciones defectuosas.