mintlify__docs/es/api-playground/mdx-setup.mdx

---
title: "Crear páginas de API manuales"
description: "Crea páginas de referencia de API manualmente con archivos MDX cuando necesitas control total del diseño para APIs pequeñas o prototipos."
keywords: ["Documentación de API", "Documentación de endpoints"]
---

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

<div id="setup">
  ## Configuración
</div>

<Steps>
  <Step title="Configura la configuración de la API">
    En tu archivo `docs.json`, configura tu URL base y el método de autenticación.

    ```json Example docs.json
    "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.

    ```json
    "api": {
      "playground": {
        "display": "none"
      }
    }
    ```

    Consulta la lista completa de configuraciones de la API en [Settings](/es/organize/settings-api).
  </Step>

  <Step title="Crea las páginas de tus endpoints">
    Crea un archivo MDX para cada endpoint. Define `title` y `api` en el frontmatter:

    ```mdx
    ---
    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 `{}`:

    ```bash
    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:

    ```mdx
    ---
    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
  </Step>

  <Step title="Añadir parámetros y respuestas">
    Utiliza los [campos de parámetros y de respuesta](/es/components/fields) para documentar los parámetros y los valores de retorno de tu endpoint.

    ```mdx
    <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>
    ```
  </Step>

  <Step title="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`:

    ```json 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](/es/organize/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:

    ```json docs.json
    "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:

    ```json docs.json
    {
      "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](/es/api-playground/openapi-setup).
  </Step>
</Steps>

<div id="enable-authentication">
  ## Habilitar la autenticación
</div>

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.

<div id="bearer-token">
  ### Token de portador
</div>

<CodeGroup>
  ```json docs.json
  "api": {
    "mdx": {
      "auth": {
        "method": "bearer"
      }
    }
  }
  ```

  ```mdx Page Metadata
  ---
  title: "Título de tu página"
  authMethod: "bearer"
  ---
  ```
</CodeGroup>

<div id="basic-authentication">
  ### Autenticación básica
</div>

<CodeGroup>
  ```json docs.json
  "api": {
    "mdx": {
      "auth": {
        "method": "basic"
      }
    }
  }
  ```

  ```mdx Page Metadata
  ---
  title: "Título de la página"
  authMethod: "basic"
  ---
  ```
</CodeGroup>

<div id="api-key">
  ### Clave de API
</div>

<CodeGroup>
  ```json docs.json
  "api": {
    "mdx": {
      "auth": {
        "method": "key",
        "name": "x-api-key"
      }
    }
  }
  ```

  ```mdx Page Metadata
  ---
  title: "Título de tu página"
  authMethod: "key"
  ---
  ```
</CodeGroup>

<div id="none">
  ### Ninguno
</div>

Para desactivar la autenticación en una página específica, configura `authMethod` como `none`:

```mdx Page Metadata
---
title: "Título de tu página"
authMethod: "none"
---
```