Saltar al contenido principal
Si tus páginas de la API no se muestran correctamente, revisa estos problemas de configuración comunes:
En este escenario, es probable que Mintlify no pueda encontrar tu documento de OpenAPI o que tu documento de OpenAPI sea inválido.Ejecutar mint dev localmente debería revelar algunos de estos problemas.Para verificar que tu documento de OpenAPI pasará 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 pasado la validación. Este es exactamente el 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 admite 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):
Esto suele deberse a que el campo openapi está mal escrito en la metadata de la página. Asegúrate de que el método HTTP y la ruta coincidan exactamente con el método HTTP y la ruta del documento de OpenAPI.Aquí tienes un ejemplo de cómo podrían salir mal las cosas:
get-user.mdx
---
openapi: "GET /users/{id}/"
---
openapi.yaml
paths:
  "/users/{id}":
    get: ...
Observa que la ruta en el campo openapi tiene una barra final, mientras que la ruta en el documento de OpenAPI no la tiene.Otro problema común es un nombre de archivo mal escrito. Si estás especificando un documento de OpenAPI en particular en el campo openapi, asegúrate de que el nombre de 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
---
openapi: "v1 GET /users/{id}"
---
Si tienes un domain personalizado configurado, esto podría deberse a 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 tu proxy inverso está configurado para permitir solo 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 te 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. 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 estás utilizando una configuración de navigation de OpenAPI, pero las páginas no se generan, revisa estos problemas comunes:
  1. Falta la especificación predeterminada de OpenAPI: Asegúrate de tener un campo openapi establecido para el elemento de navigation:
"navigation": {
  "groups": [
    {
      "group": "Referencia de API",
      "openapi": "/path/to/openapi.json",
      "pages": [
        "GET /users",
        "POST /users"
      ]
    }
  ]
}
  1. Herencia de la especificación OpenAPI: Si usas navigation anidada, asegúrate de que los grupos secundarios hereden la especificación de OpenAPI correcta o definan la suya propia.
  2. Problemas de validación: Usa mint openapi-check <path-to-openapi-file> para verificar que tu documento de 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 desde una especificación de OpenAPI, solo las operaciones referenciadas explícitamente aparecerán en la navigation. No se agregarán otras páginas automáticamente. Esto incluye las operaciones referenciadas en elementos secundarios de la navigation.
Al combinar operaciones de OpenAPI con páginas de documentación regulares 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 tener un archivo que comparta nombre con una operación, usa la extensión x-mint para el endpoint para que el href apunte a una ubicación diferente.
  2. Resolución de rutas: Las entradas de navigation que no coincidan con operaciones de OpenAPI se tratarán como rutas de archivo. Asegúrate de que tus archivos MDX existan en las ubicaciones previstas.
  3. Diferenciación entre mayúsculas y minúsculas: La coincidencia de operaciones de OpenAPI distingue entre mayúsculas y minúsculas. Asegúrate de que los métodos HTTP estén en mayúsculas en las entradas de navigation.
⌘I