Saltar al contenido principal
Puedes definir manualmente endpoints de la API en archivos MDX individuales en lugar de usar una especificación de 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 de OpenAPI para la mayoría de los proyectos porque es más fácil de mantener y más completo. No obstante, crear páginas MDX para una API puede ser útil para documentar APIs pequeñas o para prototipos. Para generar páginas de endpoints de la API usando MDX, configura los ajustes de 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 la API interactivas, ejemplos de solicitudes y ejemplos de respuestas.
1

Configura tu API

En tu archivo docs.json, define la 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"
  }
}
Consulta la lista completa de configuraciones de la API en Settings.
2

Crea las páginas de tus endpoints

Cada página de endpoint de la 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, encerrado entre {}:
https://api.example.com/v1/endpoint/{userId}
Si tienes un campo server configurado en docs.json, puedes usar rutas relativas como /v1/endpoint.
Puedes reemplazar el modo de visualización definido globalmente para el área de pruebas de la API en una página añadiendo 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 de una página tendrá prioridad sobre el método global si ambos están configurados.

​
Token de portador

"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 definir un valor predeterminado en docs.json. 
---
title: "Your page title"
authMethod: "none"
---
⌘I