Saltar al contenido principal
Puedes definir manualmente endpoints de API en archivos MDX individuales en lugar de usar una especificación OpenAPI. Este método ofrece flexibilidad para contenido personalizado, pero recomendamos generar la documentación de la API a partir de un archivo de especificación OpenAPI para la mayoría de los proyectos porque es más fácil de mantener y más completo en funcionalidades. Aun así, crear páginas MDX para una API puede ser útil para documentar APIs pequeñas o para prototipado. Para generar páginas para endpoints de API usando MDX, configura tu API en docs.json, crea archivos MDX individuales para cada endpoint y usa componentes como <ParamFields /> para definir parámetros. A partir de estas definiciones, Mintlify genera áreas de pruebas de API interactivas, ejemplos de solicitudes y de respuestas.
1

Configura tu API

En tu archivo docs.json, define tu URL base y el método de autenticación:
 "api": {
  "mdx": {
    "server": "https://mintlify.com/api", // string array for multiple base URLs
    "auth": {
      "method": "key",
      "name": "x-api-key" // options: bearer, basic, key.
    }
  }
}
Si quieres ocultar el área de pruebas de la API, usa el campo display. No necesitas incluir un método de autenticación si ocultas el área de pruebas.
"api": {
  "playground": {
    "display": "none"
  }
}
Encuentra la lista completa de configuraciones de API en Settings.
2

Crea las páginas de tus endpoints

Cada página de endpoint de API debe tener un archivo MDX correspondiente. En la parte superior de cada archivo, define title y api:
---
title: 'Create new user'
api: 'POST https://api.mintlify.com/user'
---
Puedes especificar parámetros de ruta añadiendo el nombre del parámetro a la ruta, entre llaves {}:
https://api.example.com/v1/endpoint/{userId}
Si tienes un campo server configurado en docs.json, puedes usar rutas relativas como /v1/endpoint.
Puedes anular el modo de visualización definido globalmente para el área de pruebas de la API en una página agregando playground al frontmatter:
---
title: 'Create new user'
api: 'POST https://api.mintlify.com/user'
playground: 'none'
---
  • playground: 'interactive' - Muestra el área de pruebas interactiva.
  • playground: 'simple' - Muestra un endpoint copiable sin área de pruebas.
  • playground: 'none' - Oculta el área de pruebas.
3

Agrega tus endpoints a tu documentación

Agrega las páginas de tus endpoints a la barra lateral añadiendo las rutas al campo navigation en tu docs.json. Obtén más información sobre cómo estructurar tu documentación en Navigation.

​
Habilitar la autenticación

Puedes añadir un método de autenticación a tu docs.json para habilitarla globalmente en todas las páginas, o configurarlo por página. El método de autenticación definido en una página tendrá prioridad sobre el global si ambos están configurados.

​
Token Bearer

"api": {
    "mdx": {
      "auth": {
        "method": "bearer"
      }
    }
}

​
Autenticación básica

"api": {
    "mdx": {
      "auth": {
        "method": "basic"
      }
    }
}

​
Clave de API

"api": {
    "mdx": {
      "auth": {
        "method": "key",
        "name": "x-api-key"
      }
    }
}

​
Ninguno

El método de autenticación none es útil para desactivar la autenticación en un endpoint específico después de establecer un valor predeterminado en docs.json. 
---
title: "Your page title"
authMethod: "none"
---