> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify-mintlify-15009a8b.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Solución de problemas

> Resuelve problemas comunes de configuración del área de pruebas de API, como errores de validación de OpenAPI, endpoints faltantes y problemas de autenticación.

Si sus páginas de la API no se muestran correctamente, revise estos problemas de configuración habituales.

<AccordionGroup>
  <Accordion title="Todas mis páginas de OpenAPI están completamente en blanco">
    En este escenario, es probable que Mintlify no pueda encontrar tu documento de OpenAPI
    o que tu documento de OpenAPI no sea válido.

    Ejecutar `mint dev` localmente debería revelar algunos de estos problemas.

    Para comprobar que tu documento de OpenAPI pasa la validación:

    1. Visita [este validador](https://editor.swagger.io/)
    2. Cambia a la pestaña "Validate text"
    3. Pega tu documento de OpenAPI
    4. Haz clic en "Validate it!"

    Si el cuadro de texto que aparece abajo tiene un borde verde, tu documento ha superado la validación.
    Este es exactamente el mismo paquete de validación que utiliza Mintlify para validar documentos de OpenAPI, así que si tu documento
    pasa la validación aquí, hay muchas probabilidades de que el problema esté en otra parte.

    Además, Mintlify no es compatible con OpenAPI 2.0. Si tu documento usa esta versión de la especificación,
    podrías encontrarte con este problema. Puedes convertir tu documento en [editor.swagger.io](https://editor.swagger.io/) (en Edit > Convert to OpenAPI 3):

    <Frame>
      <img src="https://mintcdn.com/mintlify-mintlify-15009a8b/4aTWuFU3TbU1kQUA/images/convert-oas-3.png?fit=max&auto=format&n=4aTWuFU3TbU1kQUA&q=85&s=ffe44180fc955656a76a90e65c4bba2b" alt="Captura de pantalla de Swagger Editor con el menú Edit desplegado y el elemento de menú &#x22;Convert to OpenAPI 3&#x22; resaltado." width="1454" height="592" data-path="images/convert-oas-3.png" />
    </Frame>
  </Accordion>

  <Accordion title="Una de mis páginas de OpenAPI está completamente en blanco">
    Esto suele deberse a un campo `openapi` mal escrito en la metadata de la página. Asegúrate de que
    el método HTTP y la ruta coincidan con el método HTTP y la ruta del documento de OpenAPI.

    <Note>
      Mintlify resuelve automáticamente las diferencias de barra final entre tu referencia `openapi`
      y la especificación de OpenAPI. Por ejemplo, `GET /users/{id}/` coincide con una ruta de la especificación `/users/{id}`.
    </Note>

    Aquí tienes un ejemplo de cómo puede salir mal:

    ```mdx get-user.mdx theme={null}
    ---
    openapi: "GET /user/{id}"
    ---
    ```

    ```yaml openapi.yaml theme={null}
    paths:
      "/users/{id}":
        get: ...
    ```

    Observa que la ruta en el campo `openapi` dice `/user/{id}` (singular), mientras que la ruta en el documento de OpenAPI es `/users/{id}` (plural).

    Otro problema común es un nombre de archivo mal escrito. Si especificas un documento de OpenAPI en particular en el campo `openapi`, asegúrate de que el nombre del archivo sea correcto. Por ejemplo, si tienes dos documentos de OpenAPI `openapi/v1.json` y `openapi/v2.json`, tu metadata podría verse así:

    ```mdx api-reference/v1/users/get-user.mdx theme={null}
    ---
    openapi: "v1 GET /users/{id}"
    ---
    ```
  </Accordion>

  <Accordion title="Las solicitudes del área de pruebas de la API no funcionan">
    Si tienes un domain personalizado configurado, esto podría deberse a un problema con tu proxy inverso. De forma predeterminada,
    las solicitudes realizadas a través del área de pruebas de la API comienzan con una solicitud `POST` a la
    ruta `/_mintlify/api/request` en el sitio de documentación. Si configuras tu proxy inverso para permitir únicamente solicitudes `GET`
    entonces todas estas solicitudes fallarán. Para solucionarlo, configura tu proxy inverso para
    permitir solicitudes `POST` a la ruta `/_mintlify/api/request`.

    Como alternativa, si tu proxy inverso impide aceptar solicitudes `POST`, puedes configurar Mintlify para enviar solicitudes directamente a tu backend con el ajuste `api.playground.proxy` en el `docs.json`, como se describe en la [documentación de configuración](/es/organize/settings-api). Al usar esta configuración, deberás configurar CORS en tu servidor, ya que las solicitudes llegarán directamente desde los navegadores de los usuarios en lugar de pasar por tu proxy.
  </Accordion>

  <Accordion title="Las solicitudes del área de pruebas de la API fallan con un error de CORS">
    Un error de CORS se produce cuando tu navegador bloquea una solicitud entre orígenes porque a la respuesta le faltan los encabezados requeridos. Puedes identificar un error de CORS en la consola de desarrollador de tu navegador: busca mensajes como que falta `Access-Control-Allow-Origin` o `blocked by CORS policy`.

    Los errores de CORS solo afectan a las solicitudes que van directamente desde el navegador del usuario a tu API. De forma predeterminada, Mintlify redirige las solicitudes del área de pruebas de la API a través de `/_mintlify/api/request`, por lo que la mayoría de los sitios no se encuentran con problemas de CORS. Normalmente ves errores de CORS cuando:

    * Has establecido `api.playground.proxy` en `false` en tu `docs.json`, por lo que las solicitudes omiten el proxy de Mintlify.
    * Has configurado una URL personalizada en `api.playground.proxy` que apunta directamente a tu backend.

    Para corregir los errores de CORS, configura tu servidor de API para que devuelva los siguientes encabezados de respuesta en las solicitudes provenientes del origen de tu sitio de documentación:

    * `Access-Control-Allow-Origin`: El origen de tu sitio de documentación (por ejemplo, `https://docs.your-site.com`) o `*` para APIs públicas.
    * `Access-Control-Allow-Methods`: Los métodos HTTP que admite tu API (por ejemplo, `GET, POST, PUT, DELETE, OPTIONS`).
    * `Access-Control-Allow-Headers`: Los encabezados que envían tus solicitudes (por ejemplo, `Content-Type, Authorization`).

    Tu servidor también debe manejar las solicitudes de preflight `OPTIONS`. Si no puedes modificar tu servidor de API, elimina el ajuste `api.playground.proxy` para que las solicitudes vuelvan a enrutarse a través del proxy de Mintlify.
  </Accordion>

  <Accordion title="Las entradas de navigation de OpenAPI no generan páginas">
    Si usas una configuración de navigation de OpenAPI, pero las páginas no se generan, revisa estos problemas comunes:

    1. **Falta la especificación de OpenAPI predeterminada**: Asegúrate de tener definido un campo `openapi` en el elemento de navigation:

    ```json {5} theme={null}
    "navigation": {
      "groups": [
        {
          "group": "Referencia de API",
          "openapi": "/path/to/openapi.json",
          "pages": [
            "GET /users",
            "POST /users"
          ]
        }
      ]
    }
    ```

    2. **Herencia de la especificación OpenAPI**: Si usas navigation anidada, asegúrate de que los grupos hijos hereden la especificación OpenAPI correcta o definan la suya propia.

    3. **Problemas de validación**: Usa `mint validate` para verificar que tu documento OpenAPI sea válido.
  </Accordion>

  <Accordion title="Algunas operaciones de OpenAPI aparecen en navigation, pero otras no">
    1. **Operaciones ocultas**: Las operaciones marcadas con `x-hidden: true` en tu especificación de OpenAPI no aparecerán en la navigation generada automáticamente.
    2. **Operaciones no válidas**: Las operaciones con errores de validación en la especificación de OpenAPI pueden omitirse. Revisa tu documento de OpenAPI para detectar errores de sintaxis.
    3. **Inclusión manual vs. automática**: Si haces referencia a endpoints de una especificación de OpenAPI, solo las operaciones referenciadas explícitamente aparecen en la navigation. No se agregan otras páginas automáticamente. Esto incluye operaciones referenciadas en elementos secundarios de la navigation.
  </Accordion>

  <Accordion title="La navigation combinada (páginas de OpenAPI y MDX) no funciona correctamente">
    Al combinar operaciones de OpenAPI con páginas de documentación estándar en navigation:

    1. **Conflictos de archivos**: No puedes tener a la vez un archivo `MDX` y una entrada en navigation para la misma operación. Por ejemplo, si tienes `get-users.mdx`, no incluyas también `"GET /users"` en tu navigation. Si necesitas un archivo que comparta nombre con una operación, usa la extensión `x-mint` del endpoint para que el href apunte a otra ubicación.
    2. **Resolución de rutas**: Las entradas en navigation que no coincidan con operaciones de OpenAPI se tratan como rutas de archivo. Asegúrate de que tus archivos `MDX` existan en las ubicaciones esperadas.
    3. **Distinción entre mayúsculas y minúscculas**: La coincidencia de operaciones de OpenAPI distingue mayúsculas y minúsculas. Asegúrate de que los métodos HTTP estén en mayúsculas en las entradas de navigation.
  </Accordion>
</AccordionGroup>