Gerenciando a documentação da API

O recurso de documentação da API no Document360 facilita a criação de documentação clara e interativa ao fazer upload dos arquivos de especificação da API. Esse processo automaticamente constrói uma documentação detalhada que cobre desde endpoints da API até métodos e respostas, ajudando os desenvolvedores a entender e usar sua API de forma mais eficaz.  

Gerando documentação de API

Existem três métodos para gerar documentação de API no Document360:

• De uma URL

• De um  arquivo JSON/YAML/YML

• Com um fluxo CI/CD

NOTA

O Document360 suporta especificações OpenAPI 2.0, OpenAPI 3.0, OpenAPI 3.1 e 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 a 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 da Nova API .

4. Selecione o botão de definição de API de upload na janela de referência da Nova API .

5. Clique em Upload do meu dispositivo ou Escolher entre 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.

NOTA

O processo de importação de documentação da API suporta subcategorias de segundo nível usando o > símbolo nas tags OpenAPI (por exemplo, Pets > Details). Isso permite uma organização mais limpa e aninhada dos endpoints, preserva a estrutura durante a ressincronização e garante exibição e navegação adequadas no painel esquerdo da referência da API.

Se o arquivo que você enviou tiver algum alerta ou alerta associado, você pode visualizá-los expandindo os menus suspensos de Alertas e Avisos , que aparecem na janela de referência da Nova API.

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

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

NOTA

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

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

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

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

2. Selecione a 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 da Nova API .

4. Na tela Escolher a fonte , selecione o botão de Criar a partir da URL e clique em Próximo.

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

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

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

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

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

Antes de enviar um arquivo de especificação de API com um fluxo CI/CD, certifique-se de que a versão mais recente do Node.js esteja instalada no seu sistema. Se você não conhece Node.js, consulte este guia para as instruções de instalação.

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

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

2. Selecione a 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 da Nova API .

4. Na tela Escolher fonte , selecione o botão de rádio CI/CD Flow .

5. Copie o comando CLI completo mostrado da janela de referência da Nova API .

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

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

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

   • Uma URL válida apontando para o arquivo de especificação da sua API. Por exemplo,

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

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

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

NOTA

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

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

Gerenciando webhooks (eventos)

Quando sua especificação OpenAPI 3.1 inclui webhooks, o Document360 os importa e mostra um ícone de evento ao lado de cada webhook. A página mostra o esquema da carga útil e o exemplo. Se a especificação não incluir um exemplo, um exemplo padrão e uma carga útil de amostra são mostrados. Tente, não está disponível para webhooks. Webhooks são incluídos nas operações de resincronização, e seu conteúdo personalizado é mantido após a regeneração.

Documentação da Regenerar API

Se você fizer qualquer alteração na sua API, como adicionar novos endpoints, não precisa atualizar manualmente a documentação da API no Document360. Você pode regenerar a documentação da sua API, e quaisquer alterações na sua API serão automaticamente refletidas na documentação atualizada.

NOTA

Qualquer conteúdo personalizado que você adicionar à sua documentação da API será mantido quando você regenerar a documentação da API.

Regenerar documentação da API a partir da URL

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

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

3. Clique em referências de API no painel de navegação da lista à esquerda.

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

   1. Para regenerar a documentação da API a partir da URL existente:

      • Clique em Resincronizar.

      • A documentação da API será regerada conforme o arquivo de especificação da API mais recente.

   

   1. Para regenerar a documentação da API com uma nova URL:

      • Clique em Editar.

      • Insira a nova URL no campo URL .

      • Clique em Atualizar.

      • A documentação da API será regerada de acordo com o arquivo de especificação da API na nova URL.

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

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

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

3. Clique em referências de API no painel de navegação da lista à esquerda.

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

5. Clique Editar.

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

7. Clique em Atualizar. A documentação da API será regerada conforme o arquivo de especificação da API mais recente.

Documentação de regenerar API integrada com fluxo CI/CD

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

Você também pode realizar 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 da API, certifique-se de que a opção de referência Mostrar download da API nas configurações do portal da Base de Conhecimento esteja ativada.

Solução de problemas

URL de servidor ausente ou incorreta na 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 as solicitações da API, e o botão "Tentar" pode não estar disponível na documentação da API. A causa raiz normalmente é uma seção ausente ou incorreta servers na especificação do OpenAPI.

Passos 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ões, defina múltiplas 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 (por exemplo, Postman, cURL) usem a URL correta do servidor ao fazer requisições.

NOTA

Os URLs acima são exemplos. Por favor, consulte a configuração específica da sua API para a URL correta do servidor.

Exemplo:

Exemplo YAML para ausência servers   Seçã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, certifique-se de que servers seção está devidamente definida na especificação OpenAPI para evitar que os consumidores de API precisem construir manualmente URLs de requisição da API.

Erro 401 não autorizado de URL incorreta do servidor

Erro: Esse erro ocorre quando as requisições de API retornam uma resposta não autorizada 401 . Normalmente acontece quando a URL do servidor incorreta é usada em requisições de API. Por exemplo, usar https://apihub.document360.io em vez de https://apihub.us.document360.io causa falhas de autenticação.

Passos para resolver:

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

1. Certifique-se de que as requisições de API utilizem o endpoint regional correto.

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

Exemplo de uma requisição correta de API:

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

NOTA

A URL acima é um exemplo. Por favor, consulte a configuração específica da sua API para a URL correta do servidor.

3. Certifique-se de que o token de autenticação esteja corretamente incluído 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 possa estar corretamente configurada na especificação da OpenAPI.

Passos para resolver:

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

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

Exemplos:

Tabela comparativa: URL do servidor presente vs. ausente

NOTA

Os URLs acima são exemplos. Por favor, consulte a configuração específica da sua API para a URL correta do servidor.

Para evitar esse problema, certifique-se de que a documentação da API especifique claramente a URL do servidor para evitar confusões.

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

Erro:

Após enviar com sucesso um arquivo OAS, clicar no recurso Tentar resulta em um erro 403. Esse erro ocorre quando o arquivo OAS está sem definição para o mecanismo de segurança BearerAuth .

Passos para resolver:

Para resolver o erro 403, siga estes passos:

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

2. Se a definição BearerAuth estiver faltando, inclua a definição de segurança BearerAuth no arquivo OAS e faça o upload novamente.

3. Durante o processo de importação, verifique se algum alerta relacionado à Autenticação do Portador foi acionado e enderece-os de acordo.

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 o escape (\") para lidar com certos caracteres com segurança. Esse escape altera caracteres como aspas, barras e linhas novas para evitar erros de transmissão de dados. No entanto, se os caracteres escapados não forem convertidos de volta (sem escape), a estrutura HTML pode quebrar, causando problemas de estilo ao serem renderizados.

Por exemplo, um simples parágrafo HTML:

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

Pode aparecer na resposta JSON como:

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

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

Passos para resolver

1. Recupere o conteúdo HTML pela API e inspecione a resposta.

2. Procure personagens fugitivos na resposta JSON, como:

   • \" (aspas duplas escapadas)

   • \\ (golpes de rejeição escapando)

   • \n (linha nova)

   • \t (tab)

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

4. Verifique o estilo após o desescabelo para garantir que o conteúdo fique correto.

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

   

   Uma vez liberado corretamente, o HTML será exibido como esperado, evitando discrepâncias de estilo.

Variáveis e Snippets não renderizando na resposta da API

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

• Se "isForDisplay" = true, a API retornará o conteúdo do artigo com todas as variáveis e trechos totalmente renderizados. Isso significa que os marcadores de lugar 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 for definido), a resposta da API conterá variáveis e trechos não processados, o que pode não ser útil 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 API sem "isForDisplay":

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

As variáveis permanecem sem processamento, tornando-o inadequado para exibição direta.

Resposta API com "isForDisplay"=true:

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

Passos para resolver:

1. Recupere o conteúdo do artigo via API e inspecione a resposta.

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

3. Certifique-se de que a solicitação da API inclua o "isForDisplay" parâmetro. Se estiver faltando, modifique a solicitação para incluir "isForDisplay": true.

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

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

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

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

7. Ao atualizar artigos via API, não passe conteúdo totalmente renderizado para evitar substituir os marcadores de posição dinâmicos por valores estáticos.

Corpo vazio mostrado na documentação da API devido à ausência do tipo de esquema

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

Passos para resolver:

Certifique-se de que cada definição de objeto na sua especificação OpenAPI inclua “type": "object”. Esse atributo especifica claramente que a estrutura definida é um objeto, ajudando a manter clareza e consistência na documentação da sua API. Ela permite que ferramentas de documentação da API renderizem com precisão parâmetros do corpo das requisições, esquemas de resposta e outras definições de objetos, facilitando para os desenvolvedores entenderem e interagirem com sua API.

Problema ao adicionar uma referência de API

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.

A possível causa pode ser que o arquivo de especificação carregado (YAML) possa estar malformado e não ser um YAML válido do OpenAPI 3.0. Isso geralmente acontece quando o arquivo é copiado ou exportado de um editor de texto enriquecido, introduzindo problemas de formatação.

Passos para resolver:

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 que podem 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.

Links úteis