Skip to main content
Si sus páginas de la API no se muestran correctamente, revise estos problemas de configuración habituales.
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.
  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 (en Edit > Convert to OpenAPI 3):
Captura de pantalla de Swagger Editor con el menú Edit desplegado y el elemento de menú "Convert to OpenAPI 3" resaltado.
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.
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}.
Aquí tienes un ejemplo de cómo puede salir mal:
get-user.mdx
openapi.yaml
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í:
api-reference/v1/users/get-user.mdx
Este error significa que Mintlify no pudo descargar el documento OpenAPI desde la URL de tu campo openapi en docs.json durante la build. Causas comunes:
  • El host no es accesible o solo se resuelve desde una red privada.
  • La URL requiere autenticación (un token, una cookie de sesión o una IP en la lista de permitidos).
  • El certificado no es válido o el dominio tiene un problema de DNS.
  • El origen devolvió un 5xx transitorio o superó el tiempo de espera.
  • La especificación se estaba republicando en el momento en que corrió la build, por lo que la URL sirvió una respuesta parcial o vacía.
Las builds descargan la URL desde la Internet pública sin credenciales, así que confirma que el documento se descarga con curl desde una máquina fuera de tu red. Para resolver el error, cambia a uno de estos patrones:
  • Sube la especificación a tu repositorio de documentación. Es el patrón recomendado cuando la URL de origen está detrás de autenticación. Apunta el campo openapi a la ruta relativa del repositorio (por ejemplo, "openapi": "openapi.json") y actualiza el archivo en el mismo commit que cambia tu API.
  • Sirve la especificación desde una URL pública HTTPS estable. Aloja el archivo en un CDN o en un bucket de almacenamiento de objetos que no requiera autenticación, tenga un certificado TLS válido y devuelva el documento completo en cada solicitud.
Para un recorrido de diagnóstico completo, incluidos los fallos intermitentes causados por CI que publica la especificación después de disparar la build, consulta La build falla con “Failed to fetch OpenAPI file for anchor or tab”.
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. Consulta la documentación de configuración para obtener más detalles. 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.
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:
  1. 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.
  2. Problemas de validación: Usa mint validate para verificar que tu documento OpenAPI sea válido.
  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.
Mintlify genera automáticamente una descripción para el campo Authorization en el área de pruebas de la API según el tipo de esquema de seguridad. Puedes sustituirla añadiendo una description al esquema de seguridad en tu especificación de OpenAPI.
La description admite Markdown y reemplaza el texto generado automáticamente en cada endpoint que use el esquema de seguridad.
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.