Añade un archivo de especificación OpenAPI
Describir tu API
- Guía de OpenAPI de Swagger para aprender la sintaxis de OpenAPI.
- Fuentes Markdown de la especificación OpenAPI para consultar detalles de la especificación OpenAPI más reciente.
- Swagger Editor para editar, validar y depurar tu documento OpenAPI.
- Mint CLI para validar tu documento OpenAPI con el comando:
mint openapi-check <openapiFilenameOrUrl>
.
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.
Especificar la URL de tu API
servers
a tu documento OpenAPI con la URL base de tu API.
/users/{id}
o simplemente /
. La URL base define dónde se deben anexar 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 la API usa estas URLs de servidor para determinar a dónde enviar las solicitudes. Si especificas varios servidores, un menú desplegable permitirá a los usuarios cambiar entre ellos. 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 existen en diferentes URLs, puedes sobrescribir el campo de servidor para una ruta u operación específica.
Especificar la autenticación
securitySchemes
y security
en tu documento OpenAPI. Las descripciones de la API y el área de pruebas de la API añadirán campos de autenticación según las configuraciones de seguridad de tu documento OpenAPI.
1
Define tu método de autenticación.
Añade un campo
securitySchemes
para definir cómo se autentican los usuarios.Este ejemplo muestra una configuración para autenticación Bearer.2
Aplica la autenticación a tus endpoints.
Añade un campo
security
para requerir autenticación.- API Keys: Para keys en encabezados, query o cookies.
- Bearer: Para tokens JWT (JSON Web Token) u OAuth.
- Basic: Para usuario y contraseña.
Extensión x-mint
x-mint
es una extensión personalizada de OpenAPI que ofrece control adicional sobre cómo se genera y se muestra la documentación de tu API.
Metadata
x-mint: metadata
a cualquier operación. Puedes usar cualquier campo de metadata que sea válido en el frontmatter de MDX
, excepto openapi
:
Contenido
x-mint: content
:
content
es compatible con todos los componentes y el formato MDX de Mintlify.
Href
x-mint: href
:
x-mint: href
está presente, la entrada de navegación enlaza directamente a la URL especificada en lugar de generar una página de API.
MCP
x-mint: mcp
. Habilita únicamente 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.
Rellenar automáticamente las páginas de la API
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 camposummary
de la operación, si está presente. Si no haysummary
, el título se genera a partir del método HTTP y el endpoint.description
: El campodescription
de la operación, si está presente.version
: El valor deversion
del ancla o Tab principal, si está presente.deprecated
: El campodeprecated
de la operación. Si estrue
, 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
x-hidden
property a la operación en tu especificación de OpenAPI.
- Secciones de API dedicadas: Haz referencia a especificaciones de OpenAPI en elementos de navigation para secciones de API dedicadas.
- Endpoints selectivos: Haz referencia a endpoints específicos en tu navigation junto con otras páginas.
Secciones de API dedicadas
openapi
a un elemento de navigation y sin otras páginas. Se incluirán todos los endpoints en la especificación:
El campo
directory
es opcional y especifica dónde se guardan las páginas de API generadas
en tu repositorio de documentación. Si no se especifica, se usará por defecto el directorio api-reference
de tu repositorio.Endpoints selectivos
Definir una especificación OpenAPI predeterminada
pages
:
METHOD /path
generará una página de API para ese endpoint usando la especificación de OpenAPI predeterminada.
Herencia de la especificación de OpenAPI
Endpoints individuales
Crear archivos MDX
para páginas de la API
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 y cómo aparece en su documentación en vivo.
Especificar archivos manualmente
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 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 configuraste una especificación de OpenAPI
predeterminada en tu navigation. Puedes referenciar cualquier endpoint de cualquier
especificación de OpenAPI incluyendo la ruta del archivo en el frontmatter.
docs.json
.
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.
Generar archivos MDX
automáticamente
MDX
para documentos extensos de OpenAPI.
Tu documento de OpenAPI debe ser válido o los archivos no se generarán automáticamente.
- Una página
MDX
por cada operación en el campopaths
de tu documento de OpenAPI. - Si tu documento de OpenAPI es versión 3.1+, una página
MDX
por cada operación en el campowebhooks
de tu documento de OpenAPI. - Un arreglo de entradas de navigation que puedes agregar a tu
docs.json
.
1
Generate `MDX` files.
2
Specify an output folder.
-o
para especificar una carpeta en la que generar 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
components.schema
de un documento de OpenAPI:
Webhooks
Define webhooks en tu especificación de OpenAPI
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.
Referencia webhooks en archivos MDX
webhook
en lugar de métodos HTTP como GET
o POST
:
El nombre del webhook debe coincidir exactamente con la key definida en el campo
webhooks
de tu especificación de OpenAPI.