Saltar al contenido principal
OpenAPI es una especificación para describir APIs. Mintlify es compatible con documentos OpenAPI 3.0+ para generar documentación de API interactiva y mantenerla actualizada.

​
Agrega un archivo de especificación de OpenAPI

Para documentar tus endpoints con OpenAPI, necesitas una especificación de OpenAPI válida en formato JSON o YAML que cumpla con la especificación OpenAPI 3.0+. Puedes hacer referencia a múltiples especificaciones de OpenAPI para crear páginas de tu API. Organiza secciones para cada especificación en la navegación o haz referencia a endpoints específicos de distintas especificaciones.
Mintlify admite $ref para referencias internas únicamente dentro de un solo documento de OpenAPI. No se admiten referencias externas.

​
Describe tu API

Recomendamos los siguientes recursos para aprender y elaborar tu especificación de OpenAPI.
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 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. 
{
  "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 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 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.
1

Define tu método de autenticación.

Agrega el campo securitySchemes para definir cómo se autentican los usuarios.Este ejemplo muestra una configuración de autenticación Bearer.
{
  "components": {
    "securitySchemes": {
      "bearerAuth": {
        "type": "http",
        "scheme": "bearer"
      }
    }
  }
}
2

Aplica la autenticación a tus endpoints.

Agrega el campo security para requerir autenticación.
{
  "security": [
    {
      "bearerAuth": []
    }
  ]
}
Los tipos de autenticación más comunes incluyen:
  • Claves de API: Para claves en encabezado, consulta o cookie.
  • Bearer: Para tokens JWT u OAuth.
  • Básica: Para usuario y contraseña.
Si distintos endpoints de tu API requieren diferentes métodos de autenticación, puedes anular el campo security para una operación determinada. Para obtener más información sobre cómo definir y aplicar la autenticación, consulta 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. 
{
  "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. 
{
  "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\n<Note>Los correos electrónicos de los usuarios deben ser únicos en todo el sistema.</Note>"
        },
        "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. 
{
  "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"
        }
      }
    }
  }
}

​
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.
​
mcp
object
La configuración de MCP para el endpoint.
{
  "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
        // ...
      }
    }
  }
}
Para obtener más información, consulta Model Context Protocol.

​
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 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. 
"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. 
"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. 
"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. 
{
  "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. 
"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. 
---
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"
---
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 de Mintlify. 
npx @mintlify/scraping@latest openapi-file <path-to-openapi-file> -o <folder-name>
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. 
---
openapi-schema: OrderItem
---
Si tienes esquemas con el mismo nombre en varios archivos, especifica el archivo de OpenAPI: 
---
openapi-schema: en-schema.json OrderItem
---

​
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 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: 
---
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.