OpenAPI es una especificación para describir API. Mintlify admite documentos de OpenAPI 3.0+ para generar documentación de API interactiva y mantenerla actualizada.

​
Agrega un archivo de especificación OpenAPI

Para documentar tus endpoints con OpenAPI, necesitas un documento OpenAPI válido en formato JSON o YAML que cumpla con la especificación OpenAPI 3.0+. Puedes crear páginas de API a partir de uno o varios documentos OpenAPI.

​
Descripción de tu API

Recomendamos los siguientes recursos para aprender y crear tus documentos de OpenAPI.
La Guía de OpenAPI de Swagger es para OpenAPI v3.0, pero casi toda la información aplica también a v3.1. Para 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.

​
Especificar la URL de tu API

Para habilitar funciones de Mintlify como el Área de pruebas de API, agrega un campo servers a tu documento de OpenAPI con la URL base de tu API. 
{
  "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 agregarse estas 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 API usa estas URL de servidor para determinar adónde enviar las solicitudes. Si especificas varios servidores, un menú desplegable permitirá a los usuarios alternar entre ellos. Si no especificas un servidor, el Área de pruebas de API usará el modo simple, ya que no puede enviar solicitudes sin una URL base. Si tu API tiene endpoints que existen en diferentes URL, puedes sobrescribir el campo servers para una ruta u operación determinada.

​
Especificar la autenticación

Para habilitar la autenticación en tu documentación y área de pruebas de API, configura los campos securitySchemes y security en tu documento de OpenAPI. Las descripciones de la API y el área de pruebas de API añadirán campos de autenticación según las configuraciones de seguridad de tu documento de OpenAPI.
1

Define tu método de autenticación.

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

Aplica la autenticación a tus endpoints.

Agrega un campo security para requerir autenticación.
{
  "security": [
    {
      "bearerAuth": []
    }
  ]
}
Los tipos comunes de autenticación incluyen:
  • API Keys: Para claves en encabezados, parámetros de consulta o cookies.
  • Bearer: Para tokens JWT u OAuth.
  • Basic: Para usuario y contraseña.
Si diferentes endpoints de tu API requieren métodos de autenticación distintos, 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.

​
Extensión x-mint

La extensión x-mint es una extensión personalizada de OpenAPI que proporciona control adicional sobre cómo se genera y se muestra la documentación de tu API.

​
Metadatos

Sobrescribe los metadatos predeterminados para las páginas de API generadas agregando 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": "Get users",
        "description": "Retrieve a list of users",
        "x-mint": {
          "metadata": {
            "title": "List all users",
            "description": "Fetch paginated user data with filtering options",
            "og:title": "Display a list of users"
          }
        },
        "parameters": [
          {
            // Parameter configuration
          }
        ]
      }
    }
  }
}

​
Contenido

Agrega contenido antes de la documentación de API generada automáticamente usando x-mint: content: 
{
  "paths": {
    "/users": {
      "post": {
        "summary": "Create user",
        "x-mint": {
          "content": "## Prerequisites\n\nThis endpoint requires admin privileges and has rate limiting.\n\n<Note>User emails must be unique across the system.</Note>"
        },
        "parameters": [
          {
            // Parameter configuration
          }
        ]
      }
    }
  }
}
La extensión content es compatible con todos los Componentes (Mintlify) de MDX y el formato.

​
Href

Cambia la URL de la página del endpoint en tu documentación usando x-mint: href: 
{
  "paths": {
    "/legacy-endpoint": {
      "get": {
        "summary": "Legacy endpoint",
        "x-mint": {
          "href": "/deprecated-endpoints/legacy-endpoint"
        }
      }
    },
    "/documented-elsewhere": {
      "post": {
        "summary": "Special endpoint",
        "x-mint": {
          "href": "/guides/special-endpoint-guide"
        }
      }
    }
  }
}
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.

​
MCP

Expón de forma selectiva endpoints como herramientas del 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.

​
Autogenerar páginas de API

Agrega 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 valores de 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 del 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, aparecerá una etiqueta de obsoleto 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 autogeneradas, agrega la propiedad 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: Referencia especificaciones de OpenAPI en elementos de navegación para secciones de API dedicadas.
  2. Endpoints selectivos: Referencia endpoints específicos en tu navegación junto con otras páginas.

​
Secciones dedicadas de API

Genera secciones dedicadas de API agregando un campo openapi a un elemento de navegación y sin incluir otras páginas. Se incluirán todos los endpoints de la especificación: 
"navigation": {
  "tabs": [
    {
        "tab": "API Reference",
        "openapi": "https://petstore3.swagger.io/api/v3/openapi.json"
    }
  ]
}
Puedes usar varias especificaciones de OpenAPI en diferentes secciones de navegación: 
"navigation": {
  "tabs": [
    {
      "tab": "API Reference",
      "groups": [
        {
          "group": "Users",
          "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 usará 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 referenciar endpoints específicos en la navegación. Este enfoque te permite generar páginas de endpoints de API junto con otros contenidos.

​
Configurar una especificación OpenAPI predeterminada

Configura una especificación OpenAPI predeterminada para un elemento de navegación. Luego, referencia endpoints específicos en el campo pages: 
"navigation": {
  "tabs": [
    {
      "tab": "Getting started",
      "pages": [
        "quickstart",
        "installation"
      ]
    },
    {
      "tab": "API reference",
      "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 la especificación 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 OpenAPI de su elemento principal, a menos que definan la suya propia: 
{
  "group": "API reference",
  "openapi": "/path/to/openapi-v1.json",
  "pages": [
    "overview",
    "authentication",
    "GET /users",
    "POST /users",
    {
      "group": "Orders",
      "openapi": "/path/to/openapi-v2.json",
      "pages": [
        "GET /orders",
        "POST /orders"
      ]
    }
  ]
}

​
Endpoints individuales

Haz referencia a endpoints específicos sin definir una especificación de OpenAPI predeterminada, incluyendo la ruta del archivo: 
"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 seleccionados.

​
Crea 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 los metadatos de la página, añadir contenido, omitir ciertas operaciones o reordenar páginas en la navegación a nivel de página. Consulta un ejemplo de página OpenAPI en MDX de MindsDB y cómo se muestra en su documentación en producción.

​
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 manera, el nombre, la descripción, los parámetros, las respuestas y el área de pruebas de 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 configurado una especificación de OpenAPI predeterminada en tu navegación. Puedes hacer referencia a cualquier endpoint de cualquier especificación de OpenAPI incluyendo la ruta del archivo en el frontmatter.
Si deseas hacer referencia a un archivo de OpenAPI externo, agrega la URL del archivo a tu docs.json. 
---
title: "Get users"
description: "Returns all plants from the system that the user has access to"
openapi: "/path/to/openapi-1.json GET /users"
deprecated: true
version: "1.0"
---
El método y la ruta deben coincidir exactamente con la definición en 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 de Mintlify para autogenerar páginas MDX a partir de documentos OpenAPI grandes.
Tu documento OpenAPI debe ser válido; de lo contrario, los archivos no se autogenerarán.
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 navegación que puedes agregar a tu docs.json.
1

Generar archivos `MDX`.

npx @mintlify/scraping@latest openapi-file <path-to-openapi-file>
2

Especificar una carpeta de salida.

npx @mintlify/scraping@latest openapi-file <path-to-openapi-file> -o api-reference
Agrega la bandera -o para especificar una carpeta donde se generarán los archivos. Si no se especifica una carpeta, los archivos se generará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 OpenAPI: 
---
openapi-schema: OrderItem
---

​
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 en documentos de OpenAPI 3.1 o superior.

​
Define webhooks en tu especificación de OpenAPI

Añade un campo webhooks a tu documento de OpenAPI junto con el campo paths. Para más información sobre cómo definir webhooks, consulta Webhooks en la documentación de OpenAPI.

​
Referenciar webhooks en archivos MDX

Al crear páginas MDX para webhooks, usa webhook en lugar de métodos HTTP como GET o POST: 
---
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 clave definida en el campo webhooks de tu especificación de OpenAPI.