Troubleshooting

Páginas de API são complicadas. Como resultado, há muitas coisas que podem dar errado. Aqui está uma lista de problemas comuns que vimos os clientes enfrentarem:

Todas as minhas páginas OpenAPI estão completamente em branco

Neste cenário, é provável que o Mintlify não consiga encontrar seu documento OpenAPI, ou seu documento OpenAPI é inválido.

Executar mint dev localmente deve revelar alguns desses problemas.

Para verificar se seu documento OpenAPI passará na validação:

1. Visite este validador
2. Mude para a aba “Validate text”
3. Cole seu documento OpenAPI
4. Clique em “Validate it!”

Se a caixa de texto que aparece abaixo tiver uma borda verde, seu documento passou na validação. Este é exatamente o pacote de validação que o Mintlify usa para validar documentos OpenAPI, então se seu documento passar na validação aqui, há uma grande chance de que o problema esteja em outro lugar.

Além disso, o Mintlify não suporta OpenAPI 2.0. Se seu documento usa esta versão da especificação, você pode encontrar este problema. Você pode converter seu documento em editor.swagger.io (em Edit > Convert to OpenAPI 3):

Uma das minhas páginas OpenAPI está completamente em branco

Isso geralmente é causado por um campo openapi mal escrito nos metadados da página. Certifique-se de que o método HTTP e o caminho correspondam exatamente ao método HTTP e ao caminho no documento OpenAPI.

Aqui está um exemplo de como as coisas podem dar errado:

get-user.mdx

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

openapi.yaml

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

Observe que o caminho no campo openapi tem uma barra no final, enquanto o caminho no documento OpenAPI não tem.

Outro problema comum é um nome de arquivo mal escrito. Se você está especificando um documento OpenAPI específico no campo openapi, certifique-se de que o nome do arquivo esteja correto. Por exemplo, se você tem dois documentos OpenAPI openapi/v1.json e openapi/v2.json, seus metadados podem parecer assim:

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

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

As requisições do API Playground não funcionam

Se você tem um domínio personalizado configurado, isso pode ser um problema com seu proxy reverso. Por padrão, as requisições feitas através do API Playground começam com uma requisição POST para o caminho /api/request no site de documentação. Se seu proxy reverso estiver configurado para permitir apenas requisições GET, então todas essas requisições falharão. Para corrigir isso, configure seu proxy reverso para permitir requisições POST para o caminho /api/request.

Alternativamente, se seu proxy reverso impede você de aceitar requisições POST, você pode configurar o Mintlify para enviar requisições diretamente para seu backend com a configuração api.playground.proxy no docs.json, como descrito aqui. Isso provavelmente exigirá que você configure o CORS em seu servidor, já que essas requisições agora virão diretamente dos navegadores dos seus usuários.