Solução de problemas

Problemas comuns em Referências de API

Se suas páginas de API não estiverem sendo exibidas corretamente, verifique estas configurações comuns:

All of my OpenAPI pages are completely blank

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

Executar mint dev localmente deve revelar alguns desses problemas.

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

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

Se a caixa de texto exibida abaixo tiver uma borda verde, seu documento passou na validação. Este é exatamente o mesmo pacote de validação que o Mintlify utiliza para validar documentos OpenAPI; portanto, 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 oferece suporte ao OpenAPI 2.0. Se seu documento usar essa versão da especificação, você pode encontrar esse problema. Você pode converter seu documento em editor.swagger.io (em Edit > Convert to OpenAPI 3):

One of my OpenAPI pages is completely blank

Isso geralmente é causado por um campo openapi com erro de digitação 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.

Veja um exemplo de como isso pode dar errado:

get-user.mdx

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

openapi.yaml

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

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

Outro problema comum é um nome de arquivo escrito incorretamente. Se você estiver especificando um documento OpenAPI em particular no campo openapi, verifique se o nome do arquivo está correto. Por exemplo, se você tiver dois documentos OpenAPI openapi/v1.json e openapi/v2.json, seus metadados podem ficar assim:

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

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

Requests from the API Playground don't work

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

Como alternativa, se o seu proxy reverso impedir o aceite de requisições POST, você pode configurar o Mintlify para enviar solicitações diretamente ao seu backend usando a opção api.playground.proxy no docs.json, conforme descrito na documentação de configurações. Ao usar essa configuração, você precisará configurar o CORS no seu servidor, já que as solicitações virão diretamente dos navegadores dos usuários em vez de passar pelo seu proxy.

OpenAPI navigation entries are not generating pages

Se você estiver usando uma configuração de navegação do OpenAPI, mas as páginas não estiverem sendo geradas, verifique estes problemas comuns:

1. Falta de especificação OpenAPI padrão: Certifique-se de que há um campo openapi definido para o elemento de navegação:

"navigation": {
  "groups": [
    {
      "group": "API reference",
      "openapi": "/path/to/openapi.json",
      "pages": [
        "GET /users",
        "POST /users"
      ]
    }
  ]
}

2. Herança da especificação OpenAPI: Se estiver usando navegação aninhada, verifique se os grupos filhos herdam a especificação OpenAPI correta ou definem a sua própria.

3. Problemas de validação: Use mint openapi-check <path-to-openapi-file> para verificar se o seu documento OpenAPI é válido.

Some OpenAPI operations appear in navigation but others don't

1. Operações ocultas: Operações marcadas com x-hidden: true na especificação OpenAPI não aparecerão na navegação gerada automaticamente.
2. Operações inválidas: Operações com erros de validação na especificação OpenAPI podem ser ignoradas. Verifique seu documento OpenAPI em busca de erros de sintaxe.
3. Inclusão manual vs. automática: Se você fizer referência a endpoints de uma especificação OpenAPI, apenas as operações explicitamente referenciadas aparecerão na navegação. Nenhuma outra página será adicionada automaticamente. Isso inclui operações referenciadas em elementos de navegação filhos.

Mixed navigation (OpenAPI and MDX pages) not working correctly

Ao combinar operações OpenAPI com páginas de documentação comuns na navegação:

1. Conflitos de arquivos: Não é possível ter um arquivo MDX e uma entrada de navegação para a mesma operação. Por exemplo, se você tiver get-users.mdx, não inclua também "GET /users" na navegação. Se precisar de um arquivo que compartilhe o nome de uma operação, use a extensão x-mint no endpoint para fazer o href apontar para outro local.
2. Resolução de caminhos: Entradas de navegação que não correspondem a operações OpenAPI serão tratadas como caminhos de arquivo. Verifique se seus arquivos MDX existem nos locais esperados.
3. Sensibilidade a maiúsculas e minúsculas: A correspondência de operações OpenAPI diferencia maiúsculas de minúsculas. Verifique se os métodos HTTP estão em maiúsculas nas entradas de navegação.