Saltar al contenido principal
Puedes definir endpoints de API manualmente en páginas MDX individuales. Este enfoque es útil para APIs pequeñas o para crear prototipos.

​
Configuración

1

Configura la configuración de la API

En tu archivo docs.json, configura tu URL base y el método de autenticación.
"api": {
  "mdx": {
    "server": "https://mintlify.com/api",
    "auth": {
      "method": "key",
      "name": "x-api-key"
    }
  }
}
Si quieres ocultar el área de pruebas de la API, configura el campo display como none. No necesitas incluir ningún método de autenticación si ocultas el área de pruebas de la API.
"api": {
  "playground": {
    "display": "none"
  }
}
Consulta la lista completa de configuraciones de la API en Settings.
2

Crea las páginas de tus endpoints

Crea un archivo MDX para cada endpoint. Define title y api en el frontmatter:
---
title: 'Crear nuevo usuario'
api: 'POST https://api.mintlify.com/user'
---
Especifica los parámetros de ruta colocándolos entre {}:
https://api.example.com/v1/endpoint/{userId}
Si tienes configurado un campo server en docs.json, puedes usar rutas relativas como /v1/endpoint.
Para anular el modo de visualización global del playground en una página específica, añade playground al frontmatter:
---
title: 'Crear nuevo usuario'
api: 'POST https://api.mintlify.com/user'
playground: 'none'
---
Options:
  • playground: 'interactive' - Mostrar el playground interactivo (predeterminado)
  • playground: 'simple' - Mostrar un endpoint copiable sin playground
  • playground: 'none' - Ocultar el playground por completo
3

Añadir parámetros y respuestas

Utiliza los campos de parámetros y de respuesta para documentar los parámetros y los valores de retorno de tu endpoint.
<ParamField path="userId" type="string" required>
  Identificador único del usuario
</ParamField>

<ParamField body="email" type="string" required>
  Dirección de correo electrónico del usuario
</ParamField>

<ResponseField name="id" type="string" required>
  Identificador único del usuario recién creado
</ResponseField>

<ResponseField name="email" type="string" required>
  Dirección de correo electrónico del usuario
</ResponseField>
4

Incorpora tus endpoints a tu documentación

Agrega las páginas de tus endpoints a la navegación actualizando el campo pages en tu docs.json:
docs.json
"navigation": {
  "tabs": [
    {
      "tab": "Referencia de la API",
      "groups": [
        {
          "group": "Usuarios",
          "pages": [
            "api-reference/users/create-user",
            "api-reference/users/get-user",
            "api-reference/users/update-user"
          ]
        },
        {
          "group": "Pedidos",
          "pages": [
            "api-reference/orders/create-order",
            "api-reference/orders/list-orders"
          ]
        }
      ]
    }
  ]
}
Cada ruta de página corresponde a un archivo MDX en tu repositorio de documentación. Por ejemplo, api-reference/users/create-user.mdx. Consulta más detalles sobre cómo estructurar tu documentación en Navigation.

​
Usar endpoints de OpenAPI en navigation

Si tienes una especificación de OpenAPI, puedes hacer referencia a endpoints directamente en tu navigation sin crear archivos MDX individuales. Haz referencia a endpoints específicos incluyendo la ruta del archivo de OpenAPI y el endpoint:
docs.json
"navigation": {
  "pages": [
    "introducción",
    "/path/to/users-openapi.json POST /users",
    "/path/to/orders-openapi.json GET /orders"
  ]
}
También puedes definir una especificación de OpenAPI predeterminada para un grupo de navigation y hacer referencia a los endpoints por método y ruta:
docs.json
{
  "group": "Referencia de API",
  "openapi": "/path/to/openapi-v1.json",
  "pages": [
    "descripción-general",
    "autenticación",
    "GET /users",
    "POST /users",
    {
      "group": "Pedidos",
      "openapi": "/path/to/openapi-v2.json",
      "pages": [
        "GET /orders",
        "POST /orders"
      ]
    }
  ]
}
Para más información sobre la integración de OpenAPI, consulta configuración de OpenAPI.

​
Habilitar la autenticación

Puedes configurar la autenticación de forma global en docs.json o anularla en páginas individuales usando el campo authMethod en el frontmatter. Un método definido para una página específica reemplaza la configuración global.

​
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

Para desactivar la autenticación en una página específica, configura authMethod como none:
Page Metadata
---
title: "Título de tu página"
authMethod: "none"
---