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

Entendendo a exclusão de endpoints durante a resincronização

Quando você atualiza seu arquivo de especificação de API, quaisquer endpoints que não estejam mais presentes na nova especificação são permanentemente excluídos, assim como qualquer conteúdo personalizado adicionado a essas páginas de endpoint.

Para atualizar seu arquivo de especificação da API:

1. Faça upload do arquivo de especificação atualizada da API na janela de referência Editar API .

2. Se algum endpoint for excluído, um aviso é exibido. Clique em Mostrar endpoints excluídos para revisar a lista de endpoints afetados.

3. Selecione a caixa de Confirmar para continuar para reconhecer a exclusão.

4. Clique em Atualizar para prosseguir.

Endpoints excluídos são movidos para a lixeira de reciclagem, onde podem ser visualizados por até 30 dias, mas não podem ser restaurados.

 NOTA

Se você estiver usando o endpoint da API de resync programaticamente, envie ForceImport = false sua solicitação para pré-visualizar a lista de endpoints que serão deletados sem prosseguir com a exclusão. Envie ForceImport = true para confirmar e prossiga.

Baixar a fonte da API

NOTA

Para baixar os arquivos da API, certifique-se de que o interruptor Mostrar a fonte da API para download nas configurações do portal da Base de Conhecimento esteja ativado .

Links úteis