Gerenciando a documentação da API

Planos que suportam API documentação

O recurso de documentação da API no Document360 facilita a criação de documentação clara e interativa carregando seus arquivos de especificação da API. Esse processo cria automaticamente uma documentação detalhada que abrange tudo, desde endpoints de API até métodos e respostas, ajudando os desenvolvedores a entender e usar sua API com mais eficiência.

Gerando documentação de API

Há três métodos para gerar a documentação da API no Document360:

• De um URL

• De um  arquivo JSON/YAML

• Com um fluxo de CI/CD

NOTA

O Document360 oferece suporte às especificações OpenAPI 2.0, OpenAPI 3.0, OpenAPI 3.1 e API Postman.

Gerando documentação de API a partir de um arquivo de especificação de API

Para gerar referências de API a partir de um arquivo de especificação de API (JSON/YAML/YML),

1. Navegue até o projeto desejado no portal da base de conhecimento.

2. Selecione Documentação da API ({ }) na barra de navegação à esquerda.

3. Clique no menu suspenso Criar na barra de navegação superior e selecione Nova API. Isso exibirá a janela de referência Nova API .

4. Selecione a opção Carregar definição de API na janela de referência Nova API .

5. Clique em Carregar do meu dispositivo ou Escolher do Drive para selecionar o arquivo do seu dispositivo ou do Document360 Drive, respectivamente. Você também pode arrastar e soltar seu arquivo diretamente na janela de referência da Nova API .

Se o arquivo carregado tiver alertas ou avisos associados, você poderá visualizá-los expandindo os menus suspensos Alertas e Avisos que aparecem na janela de referência Nova API.

6. Clique em Nova referência de API para navegar até a janela Confirmação de publicação . Você verá uma mensagem de sucesso na janela, juntamente com o número de categorias e artigos que foram criados.

7. Clique em Publicar para gerar a documentação da API.

NOTA

Para revisar sua documentação antes de publicar, clique em Fechar para retornar à tela Documentação. Seu rascunho ficará visível no painel Categorias e artigos .

Gerando documentação de API a partir de uma URL

Para carregar o arquivo de especificação da API como um URL para o Document360,

1. Navegue até o projeto desejado no portal da base de conhecimento.

2. Selecione Documentação da API ({ }) na barra de navegação à esquerda.

3. Clique no menu suspenso Criar na barra de navegação superior e selecione Nova API ou clique no botão Nova API no canto superior direito. Isso exibirá o painel de referência Nova API .

4. Na tela Escolher fonte , selecione o botão de opção Criar a partir da URL e clique em Avançar.

5. Na tela Configurações de origem , insira a URL do arquivo de especificação da API no campo URL .

6. Clique em Adicionar referência de API para navegar até a tela Concluir .

7. Na tela Concluir , você poderá ver o número de categorias e artigos que foram criados para o arquivo de especificação da API.

8. Clique em Publicar para gerar a documentação da API.

NOTA

Se você deseja verificar a documentação da API antes de publicar, clique em Fechar na tela Concluir para retornar à tela Documentação. Você poderá ver os rascunhos da documentação da API no painel Categorias e artigos .

Gerando documentação de API com um fluxo de CI/CD

Antes de carregar um arquivo de especificação de API com um fluxo de CI/CD, certifique-se de que a versão mais recente do Node.js esteja instalada em seu sistema. Se você não estiver familiarizado com Node.js, consulte this guide para obter instruções de instalação.

Para carregar o arquivo de especificação da API com um fluxo de CI/CD,

1. Navegue até o projeto desejado no portal da base de conhecimento.

2. Selecione API documentation ({ }) na barra de navegação esquerda.

3. Clique no menu suspenso Criar na barra de navegação superior e selecione Nova API. Isso exibirá o pop-up de referência da Nova API .

4. Na tela Escolher origem , selecione o botão de opção Fluxo de CI/CD e clique em Avançar.

5. Copie o comando CLI completo mostrado no pop-up de referência da Nova API.

6. No comando copiado, atualize o --path valor com:

   • O caminho completo para o arquivo de especificação JSON/YAML/YML local. Por exemplo

     --path=/Users/yourname/projects/api/openapi.yaml

   • Um URL válido apontando para o arquivo de especificação da API. Por exemplo

     --path=https://example.com/api/openapi.yaml

7. Cole o comando atualizado em seu terminal e pressione Enter.  

8. Seu arquivo de especificação da API será carregado e a documentação da APIserá gerada.

NOTA

• A primeira linha (npm install d360 -g) instala a ferramenta CLI do Document360. Você só precisa executá-lo na primeira vez. Se já estiver instalado, você pode pular essa linha.

• Se você regenerar a chave de API clicando no ícone () na interface do usuário, deverá atualizar o --apiKey valor no comando da CLI antes de executá-lo novamente. A chave antiga não será mais válida.

Regenerar documentação da API

Se você fizer alterações em sua API, como adicionar endpoints, não precisará atualizar manualmente a documentação da API no Document360. Você pode simplesmente regenerar a documentação da API e todas as alterações na API serão refletidas automaticamente na documentação da API.

NOTA

Qualquer conteúdo personalizado que você adicionar à documentação da API será retido quando você gerar novamente a documentação da API.

Regenerar a documentação da API a partir do URL

1. Navegue até o projeto desejado no portal da base de conhecimento.

2. Selecione Documentação da API ({ }) nabarra de navegação à esquerda.

3. Clique em Referência de documentos da API no painel esquerdo da lista de navegação.

4. Clique no ícone Mais () ao lado da referência de API desejada para a qual você deseja gerar novamente a documentação da API.

   1. Para gerar novamente a documentação da API a partir do URL existente:

      • Clique em Ressincronizar.

      • A documentação da API será regenerada de acordo com o arquivo de especificação da API mais recente.

   2. Para gerar novamente a documentação da API com um novo URL:

      • Clique em Editar.

      • Insira o novo URL no campo URL .

      • Clique em Atualizar.

      • A documentação da API será regenerada de acordo com o arquivo de especificação da API no novo URL.

Regenerar a documentação da API a partir de um arquivo de especificação da API

1. Navegue até o projeto desejado no portal da base de conhecimento.

2. Selecione Documentação da API ({}) na barra de navegação à esquerda.

3. Clique em Referência de documentos da API no painel esquerdo da lista de navegação.

4. Clique no ícone Mais () ao lado da referência de API desejada para a qual você deseja gerar novamente a documentação da API.

5. Clique Editar.

6. Carregue o arquivo de especificação de API mais recente no formato JSON/YAML.

7. Clique em Atualizar. A documentação da API será regenerada de acordo com o arquivo de especificação da API mais recente.

Regenerar documentação da API integrada ao fluxo de CI/CD

Você pode ressincronizar a referência de API em seus pipelines de CI/CD com a ajuda de seus pacotes npm do d360. O D360 é a ferramenta de linha de comando que ajuda você a configurar fluxos de trabalho que sincronizam seus documentos de API com o Document360.

Você também pode executar a ressincronização manualmente usando o comando abaixo.

d360 apidocs:resync 
                    --apiKey=API_key_value
                    --userId=user_id_value
                    --apiReferenceId=API_reference_value
                    --path=Spec_file_path

Baixar referência da API

NOTA

Para baixar os arquivos de API, certifique-se de que a opção Mostrar referência de API de download nas configurações do portal da base de conhecimento esteja ativada.

Solucionando problemas

URL do servidor ausente ou incorreto no OpenAPI

Erro: esse erro ocorre quando a URL do servidor está ausente ou configurada incorretamente na especificação OpenAPI. Como resultado, os usuários da API não sabem para onde enviar solicitações de API e o botão "Experimentar" pode não estar disponível na documentação da API. A causa raiz geralmente é uma seção ausente ou incorreta servers na especificação OpenAPI.

Etapas para resolver

Para resolver esse problema, certifique-se de que a especificação OpenAPI inclua a URL correta do servidor:

1. Defina a URL do servidor na especificação OpenAPI:

   servers:
     - url: https://apihub.document360.io
       description: Main API hub

2. Para APIs baseadas em região, defina várias URLs de servidor:

   servers:
     - url: https://apihub.document360.io
       description: Global API hub
     - url: https://apihub.us.document360.io
       description: US region API hub

3. Certifique-se de que todos os clientes da API (Postman, cURL etc.) usem a URL correta do servidor ao fazer solicitações.

NOTA

Os URLs acima são exemplos. Consulte sua configuração de API específica para obter o URL correto do servidor.

Exemplo:

Exemplo de YAML para falta servers de secção:

paths:
  /users:
    get:
      summary: Retrieve a list of users
      responses:
        '200':
          description: A list of users
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    userId:
                      type: integer
                    userName:
                      type: string

Para evitar esse problema, verifique se o servers é definida corretamente na especificação OpenAPI para evitar que os consumidores de API tenham que construir manualmente URLs de solicitação de API.

Erro 401 não autorizado de URL de servidor incorreto

Erro: esse erro ocorre quando as solicitações de API retornam uma resposta 401 não autorizada. Isso normalmente acontece quando o URL do servidor incorreto é usado em solicitações de API. Por exemplo, usar https://apihub.document360.io instead of causa falhas de https://apihub.us.document360.io autenticação.

Etapas para resolver:

Para resolver esse problema, siga estas etapas para garantir o uso correto da URL do servidor e a autenticação adequada:

1. Certifique-se de que as solicitações de API usem o endpoint baseado em região correto.

2. Confirme se o ID do cliente e o segredo do cliente corretos estão sendo usados.

Exemplo de uma solicitação de API correta:

GET https://apihub.us.document360.io/v2/Articles/{article_id}/en?appendSASToken=true

NOTA

O URL acima é um exemplo. Consulte sua configuração de API específica para obter o URL correto do servidor.

3. Verifique se o token de autenticação está incluído corretamente nos cabeçalhos da solicitação.

URL do servidor ausente na documentação da API

Erro: esse problema ocorre quando os consumidores da API não têm certeza de qual URL base usar para suas solicitações. Isso normalmente acontece quando a documentação não indica claramente a URL do servidor, mesmo que ela esteja configurada corretamente na especificação OpenAPI.

Etapas para resolver:

Para evitar confusão e garantir que os consumidores da API saibam o URL base correto:

1. Especifique a URL base explicitamente na documentação da API.

Exemplos:

Tabela de comparação: URL do servidor presente vs. ausente

NOTA

Os URLs acima são exemplos. Consulte sua configuração de API específica para obter o URL correto do servidor.

Para evitar esse problema, verifique se a documentação da API especifica claramente a URL do servidor para evitar qualquer confusão.

Erro 403 ao usar o recurso "Experimentar" com um arquivo OAS

Erro:

Depois de carregar com êxito um arquivo OAS, clicar no recurso Experimentar resulta em um erro 403. Esse erro ocorre quando o arquivo OAS não tem uma definição para o mecanismo de segurança BearerAuth .

Etapas para resolver:

Para resolver o erro 403, siga estas etapas:

1. Verifique se a definição de segurança BearerAuth está presente no arquivo OAS.

2. Se a definição de BearerAuth estiver ausente, inclua a definição de segurança BearerAuth no arquivo OAS e carregue-a novamente.

3. Durante o processo de importação, verifique se algum alerta relacionado à autenticação do portador foi acionado e resolva-o adequadamente.

Estilo HTML incorreto na resposta da API

Ao recuperar o conteúdo HTML de um artigo por meio de uma API, a resposta é formatada em JSON, que usa escaping (\") para lidar com determinados caracteres com segurança. Esse escape altera caracteres como aspas, barras invertidas e novas linhas para evitar erros de transmissão de dados. No entanto, se os caracteres de escape não forem convertidos de volta (sem escape), a estrutura HTML poderá quebrar, levando a problemas de estilo quando renderizada.

Por exemplo, um parágrafo HTML simples:

<p>This is a "sample" paragraph.</p>

Pode aparecer na resposta JSON como:

"<p>This is a \"sample\" paragraph.</p>"

As aspas duplas com escape (\") garantem que o JSON permaneça válido, mas se não tiver escape, o HTML pode não ser renderizado corretamente.

Etapas para resolver

1. Recupere o conteúdo HTML por meio da API e inspecione a resposta.

2. Procure caracteres de escape na resposta JSON, como:

   • \" (aspas duplas escapadas)

   • \\ (barras invertidas escapadas)

   • \n (nova linha)

   • \t (guia)

3. Remova o escape do conteúdo JSON antes de renderizá-lo. Isso restaurará a estrutura HTML original.

4. Verifique o estilo após remover o escape para garantir que o conteúdo apareça corretamente.

5. Se o problema persistir, verifique se modificações adicionais em seu código estão alterando a resposta da API.

   

   Uma vez sem escape corretamente, o HTML será exibido conforme o esperado, evitando discrepâncias de estilo.

Variáveis e snippets não renderizados na resposta da API

Ao recuperar o conteúdo do artigo por meio da API, variáveis e snippets podem aparecer não processados (por exemplo, {{variable.UserName}} em vez de valores reais). Isso normalmente acontece quando o "isForDisplay" parâmetro não está definido corretamente.

• Se "isForDisplay" = true, a API retornará o conteúdo do artigo com todas as variáveis e snippets totalmente renderizados. Isso significa que os espaços reservados são substituídos por valores reais, tornando o conteúdo adequado para exibição aos usuários finais.

• Se "isForDisplay" = false (ou não definido), a resposta da API conterá variáveis e snippets não processados, que podem não ser úteis para exibição direta.

  Se o problema persistir após seguir essas etapas, entre em contato com a equipe de suporte do Document360 para obter mais assistência: Entre em contato com o suporte do Document360

Conteúdo do artigo na base de conhecimento:

Welcome, {{variable.UserName}}! Here’s how to use {{variable.ProductName}}.

Resposta da API sem "isForDisplay":

"Welcome, {{variable.UserName}}! Here’s how to use {{variable.ProductName}}."

As variáveis permanecem não processadas, tornando-as inadequadas para exibição direta.

Resposta da API com "isForDisplay"=true:

"Welcome, John! Here’s how to use Document360."

Etapas para resolver:

1. Recupere o conteúdo do artigo por meio da API e inspecione a resposta.

2. Verifique se variáveis ou snippets aparecem não processados na resposta.

3. Verifique se a solicitação de API inclui o "isForDisplay" parâmetro. Se estiver ausente, modifique a solicitação para incluir "isForDisplay": true.

4. Envie a solicitação de API modificada. Exemplo de solicitação:

   {
     "articleId": "12345",
     "isForDisplay": true
   }
   

5. Verifique se a resposta da API agora exibe as variáveis e snippets renderizados corretamente.

6. Se o problema persistir, certifique-se de que o sistema que processa a resposta da API manipule e exiba o conteúdo renderizado corretamente.

7. Ao atualizar artigos por meio da API, não passe conteúdo totalmente renderizado para evitar a substituição de espaços reservados dinâmicos por valores estáticos.

Corpo vazio mostrado na documentação da API devido à falta de tipo de esquema

A documentação da API exibe um corpo vazio. A possível causa desse erro pode ser que o esquema OpenAPI não tenha o “type": "object” atributo em uma ou mais definições de objeto.

Etapas para resolver:

Certifique-se de que cada definição de objeto em sua especificação OpenAPI inclua “type": "object”. Esse atributo especifica claramente que a estrutura definida é um objeto, ajudando a manter a clareza e a consistência na documentação da API. Ele permite que as ferramentas de documentação da API renderizem com precisão os parâmetros do corpo da solicitação, esquemas de resposta e outras definições de objeto, tornando mais fácil para os desenvolvedores entender e interagir com sua API.

Links úteis