Troubleshooting

Las páginas de API son complicadas. Como resultado, hay muchas cosas que pueden salir mal. Aquí hay una lista de problemas comunes que hemos visto que los clientes enfrentan:

Todas mis páginas de OpenAPI están completamente en blanco

En este escenario, es probable que Mintlify no pueda encontrar su documento OpenAPI, o que su documento OpenAPI no sea válido.

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

Para verificar que su documento OpenAPI pase la validación:

1. Visite este validador
2. Cambie a la pestaña “Validar texto”
3. Pegue su documento OpenAPI
4. Haga clic en “¡Validarlo!”

Si el cuadro de texto que aparece debajo tiene un borde verde, su documento ha pasado la validación. Este es el paquete de validación exacto que Mintlify utiliza para validar documentos OpenAPI, por lo que si su documento pasa la validación aquí, hay una gran probabilidad de que el problema esté en otro lugar.

Además, Mintlify no admite OpenAPI 2.0. Si su documento utiliza esta versión de la especificación, podría encontrar este problema. Puede convertir su documento en editor.swagger.io (bajo Editar > Convertir a OpenAPI 3):

Una de mis páginas de OpenAPI está completamente en blanco

Esto generalmente es causado por un campo openapi mal escrito en los metadatos de la página. Asegúrese de que el método HTTP y la ruta coincidan exactamente con el método HTTP y la ruta en el documento OpenAPI.

Aquí hay un ejemplo de cómo las cosas podrían salir mal:

get-user.mdx

---
openapi: "GET /users/{id}/"
---

openapi.yaml

paths:
  "/users/{id}":
    get: ...

Observe que la ruta en el campo openapi tiene una barra diagonal al final, mientras que la ruta en el documento OpenAPI no la tiene.

Otro problema común es un nombre de archivo mal escrito. Si está especificando un documento OpenAPI particular en el campo openapi, asegúrese de que el nombre del archivo sea correcto. Por ejemplo, si tiene dos documentos OpenAPI openapi/v1.json y openapi/v2.json, sus metadatos podrían verse así:

api-reference/v1/users/get-user.mdx

---
openapi: "v1 GET /users/{id}"
---

Las solicitudes desde el Playground de API no funcionan

Si tiene configurado un dominio personalizado, esto podría ser un problema con su proxy inverso. Por defecto, las solicitudes realizadas a través del Playground de API comienzan con una solicitud POST a la ruta /api/request en el sitio de documentación. Si su proxy inverso está configurado para permitir solo solicitudes GET, entonces todas estas solicitudes fallarán. Para solucionarlo, configure su proxy inverso para permitir solicitudes POST a la ruta /api/request.

Alternativamente, si su proxy inverso le impide aceptar solicitudes POST, puede configurar Mintlify para enviar solicitudes directamente a su backend con la configuración api.playground.proxy en el docs.json, como se describe aquí. Esto probablemente requerirá que configure CORS en su servidor, ya que estas solicitudes ahora vendrán directamente de los navegadores de sus usuarios.