Configuración de la API
Configura especificaciones OpenAPI y AsyncAPI, el área de pruebas interactiva, ejemplos de código SDK y ajustes de autenticación en tu archivo docs.json.
Usa el campo api en docs.json para configurar qué especificaciones de API generan páginas de API, el área de pruebas interactiva de la API para probar endpoints, y cómo generar y mostrar ejemplos de código.
Ajustes
api
Tipo: object
Define todos los ajustes relacionados con la API bajo la clave api.
api.openapistring or array or objectArchivos de especificación OpenAPI para generar páginas de referencia de API. Acepta una única ruta o URL, un array de rutas y URLs, o un objeto que especifica una fuente y directorio.
Show Hide api.openapi object
sourcestringURL o ruta a tu archivo de especificación OpenAPI. Longitud mínima: 1.
directorystringDirectorio donde buscar archivos OpenAPI. No incluyas una barra inicial.
"openapi": "openapi.json"api.asyncapistring or array or objectArchivos de especificación AsyncAPI para generar páginas de referencia de API basadas en eventos. Acepta una única ruta o URL, un array de rutas y URLs, o un objeto que especifica una fuente y directorio.
Show Hide api.asyncapi object
sourcestringURL o ruta a tu archivo de especificación AsyncAPI. Longitud mínima: 1.
directorystringDirectorio donde buscar archivos AsyncAPI. No incluyas una barra inicial.
"asyncapi": "asyncapi.json"api.playgroundobjectConfiguración del área de pruebas interactiva de la API.
Show Hide api.playground
display"interactive" | "simple" | "none" | "auth"El modo de visualización del área de pruebas. El valor predeterminado es interactive.
interactive— Área de pruebas interactiva completa con constructor de solicitudessimple— Vista simplificada sin el constructor de solicitudesnone— Ocultar el área de pruebas por completoauth— Mostrar el área de pruebas solo a usuarios autenticados
proxybooleanSi se deben enrutar las solicitudes de API a través de un servidor proxy. El valor predeterminado es true.
credentialsbooleanIndica si se deben incluir cookies y encabezados de autenticación en las solicitudes cross-origin cuando proxy es false. El valor predeterminado es false. No tiene efecto cuando proxy es true.
api.paramsobjectConfiguración de visualización para los parámetros de la API.
Show Hide api.params
expanded"all" | "closed"Si se expanden todos los parámetros de forma predeterminada. El valor predeterminado es closed.
postarray of stringClaves de campos de la especificación OpenAPI que se mostrarán como píldoras post junto al nombre de cada parámetro en las páginas de referencia de la API y en el playground. Para cada clave que enumeres, Mintlify lee el valor del esquema y lo renderiza como una píldora:
- Los valores de cadena se renderizan como la cadena literal.
truerenderiza el nombre de la clave como etiqueta de la píldora.false,nully las cadenas vacías no renderizan nada.- Los valores numéricos renderizan el número convertido a cadena.
- Los arreglos de cadenas o números renderizan una píldora por elemento.
- Los objetos y otros valores se omiten.
Usa esto para exponer campos personalizados de OpenAPI —como x-internal, nullable o extensiones de proveedor— como anotaciones visuales en cada parámetro sin necesidad de configuración por propiedad.
api.url"full"Modo de visualización de la URL base en el encabezado del endpoint. Establece full para mostrar siempre la URL base completa en cada página de endpoint. Por defecto, la URL base solo se muestra cuando hay múltiples URLs base para seleccionar.
api.examplesobjectConfiguración para los ejemplos de código de API generados automáticamente.
Show Hide api.examples
languagesarray of stringLenguajes para los fragmentos de código generados automáticamente. Consulta lenguajes compatibles para ver la lista completa de lenguajes y alias disponibles.
defaults"required" | "all"Si se incluyen parámetros opcionales en los ejemplos generados. El valor predeterminado es all.
prefillbooleanSi se precarga el área de pruebas con valores de ejemplo de tu especificación OpenAPI. El valor predeterminado es false.
autogeneratebooleanSi se generan muestras de código para endpoints a partir de tu especificación de API. El valor predeterminado es true. Cuando se establece en false, solo aparecen en el área de pruebas las muestras de código escritas manualmente (desde x-codeSamples en OpenAPI o componentes <RequestExample> en MDX).
api.mdxobjectConfiguración para páginas de API creadas a partir de archivos MDX en lugar de especificaciones OpenAPI.
Show Hide api.mdx
authobjectConfiguración de autenticación para solicitudes de API basadas en MDX.
Show Hide auth
method"bearer" | "basic" | "key" | "cobo"Método de autenticación para las solicitudes de API.
namestringNombre del parámetro de autenticación para las solicitudes de API.
serverstring or arrayURL base que se antepone a las rutas relativas en los campos de frontmatter api a nivel de página. No se utiliza cuando el frontmatter contiene una URL completa.
Ejemplo
{
"api": {
"openapi": ["openapi/v1.json", "openapi/v2.json"],
"playground": {
"display": "interactive"
},
"params": {
"expanded": "all",
"post": ["nullable", "x-internal"]
},
"url": "full",
"examples": {
"languages": ["curl", "python", "javascript", "go"],
"defaults": "required",
"prefill": true,
"autogenerate": true
}
}
}