Crear páginas de API manuales

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://api.acme.com/",
    "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.

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 /v1/users'
---

El campo api del frontmatter acepta una URL completa o una ruta relativa:

• URL completa como POST https://api.acme.com/v1/users. El campo server en docs.json se ignora para ese endpoint.
• Ruta relativa como POST /v1/users. Requiere un campo server en docs.json. La URL del servidor se antepone a la ruta.

Especifica los parámetros de ruta colocándolos entre {}:

https://api.example.com/v1/endpoint/{userId}

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

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>
  Unique identifier for the user
</ParamField>

<ParamField body="email" type="string" required>
  User's email address
</ParamField>

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

<ResponseField name="email" type="string" required>
  User's email address
</ResponseField>

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:

"navigation": {
  "tabs": [
    {
      "tab": "Referencia de la API",
      "groups": [
        {
          "group": "Users",
          "pages": [
            "api-reference/users/create-user",
            "api-reference/users/get-user",
            "api-reference/users/update-user"
          ]
        },
        {
          "group": "Orders",
          "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:

"navigation": {
  "pages": [
    "introduction",
    "/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:

{
  "group": "Referencia de API",
  "openapi": "/path/to/openapi-v1.json",
  "pages": [
    "overview",
    "authentication",
    "GET /users",
    "POST /users",
    {
      "group": "Orders",
      "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.