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, ya que 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 hacer prototipos. 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 la API interactivas, ejemplos de solicitudes y ejemplos 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 deseas 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 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 agregando el nombre del parámetro en la ruta, 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 sustituir 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 en el campo navigation de 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 en tu docs.json para habilitarla globalmente en todas las páginas, o configurarlo de forma individual por página. El método de autenticación definido en una página reemplazará el método global si ambos están configurados.

​
Token de portador (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"
---
⌘I