Solução de problemas de importação de API

Este artigo é uma referência consolidada para todos os erros, avisos e comportamentos inesperados documentados na funcionalidade de documentação da API do Document360. Use-o para diagnosticar e resolver problemas com importações, autenticação, o recurso Try It!, renderização e o site da base de conhecimento.

Erros de importação

Formato inválido – Falha no upload do arquivo API

Quando ocorre: Quando uma ou mais respostas no seu arquivo de especificação OpenAPI estiverem faltando a seção necessária content .

Por que isso acontece: O Document360 aplica regras rigorosas de validação do OpenAPI. Embora um arquivo possa passar por validação em ferramentas como o Swagger Editor, o Document360 exige que todas as respostas definam explicitamente tanto o tipo de mídia (por exemplo, application/json) quanto uma referência de esquema sob um content bloco. Respostas vazias ou que referenciam um esquema diretamente sem um content wrapper causarão esse erro.

Como consertar:

1. Abra seu arquivo de especificação OpenAPI em um editor de texto ou IDE.
2. Localize quaisquer definições de resposta que estejam vazias ou que façam referência a um esquema sem bloco content .
   Incorreto:

   responses:
     "200": {}

Correto:

   responses:
     "200":
       description: OK
       content:
         application/json:
           schema:
             $ref: "#/components/schemas/YourSchema"

3. Salve o arquivo e faça o upload novamente para o Document360.
   Se o problema persistir, entre em contato com a equipe de suporte do Document360 .

URL inválida

Quando ocorre: Ao criar uma referência de API a partir de uma URL, a URL fornecida não pode ser buscada ou resolvida.

Por que isso acontece: A URL pode estar malformada, inacessível a partir dos servidores do Document360 ou apontando para um recurso que não seja uma especificação válida da OpenAPI.

Como consertar: Verifique se a URL se resolve corretamente em um navegador ou com curl. Certifique-se de que ele retorne um documento válido JSON ou YAML OpenAPI. Corrija a URL e tente novamente.

Formato de arquivo não suportado

Quando ocorre: Quando o arquivo enviado não é um formato suportado.

Como consertar: Certifique-se de que seu arquivo seja um dos seguintes: JSON, YAML ou YML. O Document360 suporta OpenAPI 2.0, OpenAPI 3.0, OpenAPI 3.1 e Coleções Postman.

Não foi possível adicionar referência de API – arquivo de especificação inválido

Mensagem de erro: "Não foi possível adicionar referência de API. Essa operação não pode ser concluída. Por favor, certifique-se de que forneceu um arquivo de especificação válido."

Quando ocorre: Ao enviar um arquivo de especificação YAML que foi copiado ou exportado de um editor de texto enriquecido ou processador de texto.

Por que isso acontece: O arquivo YAML enviado é malformado e não é um documento válido do OpenAPI 3.0 YAML. Isso ocorre comumente quando o arquivo foi copiado ou exportado de um editor de texto enriquecido, que introduz caracteres de formatação, como \f0\fs24 barras inversas ou finais que quebram o formato YAML.

1. Valide seu arquivo de especificações: Abra seu arquivo YAML em uma ferramenta como o Swagger Editor ou um editor de código para verificar erros ou problemas de formatação.
2. Procure caracteres de formatação indesejados: Verifique caracteres como \f0\fs24 barras \ inversas ou posteriores (especialmente na descrição do endpoint) que possam ter sido introduzidos durante o copiar-colar de uma fonte em texto rico. Esses podem quebrar o formato YAML.
3. Limpar o arquivo: Use um editor de texto simples ou código para remover quaisquer caracteres de formatação especial. Evite usar processadores de texto ao editar ou salvar arquivos YAML.
4. Refaça o upload do arquivo: Depois de limpar o arquivo e garantir que é um YAML válido da OpenAPI 3.0, tente enviá-lo novamente.

Resumo e tags não refletidos após a importação

Quando ocorre: Após importar uma especificação, os artigos finais exibem títulos incorretos ou aparecem em pastas de categorias inesperadas.

Por que isso acontece: Os summary campos e tags são definidos no nível do caminho na especificação, em vez de dentro do objeto de operação (get, post, put, ou delete). Além disso, o tags campo deve sempre ser escrito como um array, mesmo quando apenas uma tag é usada.

Como consertar:

1. Abra seu arquivo de especificação OpenAPI em um editor de texto.
2. Mova os summary campos e tags dentro de cada objeto de operação e garanta tags que está escrito como um array.
   Incorreto:

   /your-endpoint:
     summary: My Endpoint
     tags: My Category
     get:
       ...

Correto:

   /your-endpoint:
     get:
       summary: My Endpoint
       tags: ["My Category"]
       ...

3. Salve o arquivo e reimporte para o Document360. Os artigos importados usarão o summary valor como título do artigo, e pastas baseadas em tags serão criadas corretamente.
   Se o problema persistir, entre em contato com a equipe de suporte do Document360 .

Falha no upload com 400 Solicitação Ruim – arquivo de especificação grande demais

Quando ocorre: Ao fazer upload de um arquivo válido de especificação YAML ou JSON OpenAPI, que contém endpoints com esquemas de resposta profundamente aninhados e múltiplos códigos de resposta por endpoint.

Por que isso acontece: Embora o arquivo possa ser um YAML válido e passar por validadores externos como o Swagger Editor, o Document360 impõe um limite interno de tamanho de artigo. Quando um endpoint contém esquemas de resposta aninhados em oito ou mais níveis de profundidade em múltiplos códigos de resposta, o tamanho resultante dos dados excede esse limite e não pode ser processado ou armazenado.

Como consertar:

1. Abra seu arquivo de especificação OpenAPI em um editor de texto ou IDE.
2. Para cada endpoint, mantenha apenas um tipo de resposta 201, um tipo de resposta da série 400 e o tipo de resposta padrão. Remova todos os códigos de resposta adicionais.
3. Para endpoints onde a resposta 201 sozinha contém esquemas profundamente aninhados, mantenha apenas o tipo de resposta 201 e remova completamente a série 400 e os tipos de resposta padrão.
4. Salve o arquivo modificado e faça o upload novamente para o Document360.

i️ NOTA
Se a publicação falhar após um upload bem-sucedido, entre em contato com a equipe de suporte do Document360. Publicar pode exigir assistência no backend devido à limitação do tamanho do artigo.

Descrições de tags de nível superior não renderizadas na documentação da API

Quando ocorre: Descrições e metadados definidos em objetos de tag OpenAPI de nível superior não são exibidos na documentação gerada da API.

Por que isso acontece: Quando um arquivo de especificação OpenAPI contém tags de nível superior usadas para agrupar operações de API, o Document360 converte essas tags em categorias tipo pasta durante a importação. Categorias de pasta são usadas apenas para organizar endpoints e não geram páginas de conteúdo independentes. Como resultado, qualquer descrição ou metadado definido dentro desses objetos de tag de nível superior não é renderizado.

Solução alternativa: Adicione o contexto relevante diretamente às descrições individuais dos endpoints dentro da tag, para que as informações fiquem visíveis nas páginas geradas dos endpoints.

Ainda está tendo problemas?

Se os passos acima não resolverem seu problema, entre em contato diretamente com a equipe de suporte do Document360 .

FAQ