Este artigo cobre tudo o que você precisa para gerenciar suas API no Document360. Criar novas referências, mantê-las sincronizadas com sua especificação e usar as ações disponíveis para visualizar, editar, publicar e organizar a documentação da sua API.
Lista de referências de API
A lista de referências da API oferece uma visão central de todas as referências configuradas na sua área de trabalho. Para acessá-la, navegue até a documentação da API ({ }) na barra de navegação da esquerda e clique em referências da API no painel de navegação esquerdo.
A partir daí, você pode ver o nome, o tipo e a data da última atualização de cada referência. Você também pode criar uma nova referência de API clicando em Nova API no canto superior direito.
Criar uma nova referência de API
Para criar uma nova referência de API, clique no menu suspenso Criar na barra de navegação superior e selecione Nova API. Isso abre a janela de referência da Nova API, onde você tem quatro opções:
- Definição de API de upload - Envie um arquivo de especificação JSON, YAML ou YML diretamente do seu dispositivo ou do Document360 Drive.
- Criar a partir da URL - Busque sua especificação automaticamente de uma URL hospedada.
- Fluxo CI/CD - Integre com seu pipeline para atualizar automaticamente a documentação a cada alteração de especificação. Requer Node.js.
- Tente um arquivo API de Pet Store de exemplo - Use o arquivo de especificação de exemplo do Document360 para explorar o espaço de trabalho antes de enviar o seu próprio.
O Document360 suporta especificações OpenAPI 2.0, OpenAPI 3.0, OpenAPI 3.1 e Postman. Dentro de cada espaço de trabalho de API, você pode criar no máximo 3 referências de API.
Definição de API de upload
- Selecione o botão de definição de API de Upload .
- Clique em Upload do meu dispositivo para enviar do seu armazenamento local, ou Escolha entre Drive para selecionar um arquivo do Document360 Drive. Você também pode arrastar e soltar seu arquivo diretamente na janela.
- O Document360 analisa o arquivo e gera a referência da API. Se avisos forem detectados, expanda a seção Alertas e Avisos para revisá-los.
- Clique em Nova referência de API para prosseguir até a janela de confirmação de publicação.
Criar a partir da URL
- Selecione o botão de Criar a partir da URL e clique em Próximo.
- Insira a URL apontando para o arquivo de especificação da OpenAPI.
- Clique em Nova referência de API. O Document360 busca e processa a especificação.
Fluxo CI/CD
O fluxo CI/CD permite que você mantenha a documentação da API automaticamente sincronizada com sua especificação. Em vez de enviar manualmente uma nova especificação toda vez que sua API muda, você integra a CLI do Document360 ao seu pipeline para que a documentação seja atualizada automaticamente a cada alteração de especificação.
Para instruções completas de configuração, veja o artigo sobre integração CI/CD .
Ações de referência da API
Uma vez criada uma referência de API, clique no ícone More (⋯) ao lado dela na lista de referências da API para acessar as seguintes ações:
| Ação | O que ele faz |
|---|---|
| Edit | Atualize o arquivo de especificação ou URL a partir da qual a referência foi criada. |
| Resincronização | Regenere a documentação a partir da versão mais recente da especificação na URL existente. |
| Veja definição da API | Pré-visualize o arquivo bruto de especificação da API. |
| Baixe a fonte original da API | Baixe a versão atual do arquivo de especificações para o seu armazenamento local. |
| Publicar | Publique todos os artigos rascunhos na referência da API para o site da Base de Conhecimento. |
| Excluir | Exclua permanentemente a referência da API e todo o conteúdo gerado. |
| Veja registros | Revise alertas, avisos e erros da importação ou ressincronização mais recente. |
Para permitir que os leitores baixem o arquivo fonte da API a partir do site da Base de Conhecimento, certifique-se de que o interruptor Mostrar a fonte da API para download esteja ativado nas configurações do portal da Base de Conhecimento.
Mantendo sua documentação sincronizada
Quando sua API muda - novos endpoints adicionados, parâmetros atualizados, respostas modificadas, mas você não precisa atualizar sua documentação manualmente. A regeneração da referência da API puxa todas as mudanças da sua especificação automaticamente.
Qualquer conteúdo personalizado que você tenha adicionado a artigos individuais de endpoint é mantido quando você regenera sua documentação. Apenas o conteúdo gerado por especificações é atualizado.
Resincronização a partir de uma URL existente
- Na lista de referências da API, clique no ícone de Mais (⋯) ao lado da referência que você deseja atualizar.
- Clique em Resincronizar. A documentação regenera a partir da versão mais recente da especificação na URL existente.
Atualização para uma nova URL
- Clique no ícone de Mais (⋯) ao lado da referência.
- Clique em Editar.
- Insira a nova URL no campo URL .
- Clique em Atualizar.
Regenerar a partir de um arquivo de especificação
- Clique no ícone de Mais (⋯) ao lado da referência.
- Clique em Editar.
- Envie o arquivo de especificação mais recente em formatos JSON, YAML ou YML.
- Clique em Atualizar.
Resync via CI/CD
Se sua referência de API foi configurada com o fluxo CI/CD, a resincronização acontece automaticamente como parte do seu pipeline sempre que sua especificação muda. Você também pode acionar uma ressincronização manual usando o apidocs:resync comando:
d360 apidocs:resync \
--apiKey=YOUR_API_KEY \
--userId=YOUR_USER_ID \
--apiReferenceId=YOUR_API_REFERENCE_ID \
--path=PATH_TO_SPEC_FILE
Para detalhes completos sobre como configurar e gerenciar o fluxo CI/CD, veja o artigo sobre integração CI/CD .
Resincronização automática vs manual
| Método de criação | Resincronização automática | Resincronização manual |
|---|---|---|
| Upload do arquivo | Não disponível | Sim, via Editar no portal |
| Importação de URL | Não disponível | Sim, via Resync ou Editar no portal |
| Fluxo CI/CD | Sim - roda como parte do seu pipeline | Sim, execute o comando CLI manualmente |
Se você gerou sua documentação de API a partir de uma URL ou arquivo, ela não será atualizada automaticamente. Para que a documentação seja atualizada automaticamente, integre com o fluxo CI/CD.
Entendendo a exclusão de endpoints durante a resincronização
Quando você atualiza seu arquivo de especificação da API, quaisquer endpoints que não estejam mais presentes na nova especificação são permanentemente excluídos, junto com qualquer conteúdo personalizado adicionado a essas páginas de endpoint.
Para atualizar seu arquivo de especificações com segurança:
- Envie o arquivo de especificação atualizado na janela de referência Editar API .
- Se algum endpoint for excluído, um aviso é exibido. Clique em Mostrar endpoints excluídos para revisar a lista de endpoints afetados.
- Selecione a caixa de Confirmar para continuar para reconhecer a exclusão.
- 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.
Se você estiver usando o endpoint da API de resync programaticamente, envie ForceImport = false para pré-visualizar a lista de endpoints que serão excluídos sem prosseguir. Envie ForceImport = true para confirmar e prossiga.
Mantendo a documentação em rascunho
Após carregar ou ressincronizar uma especificação, você pode manter a documentação resultante em modo rascunho em vez de publicá-la imediatamente.
- Na janela de confirmação de publicação, clique em Fechar em vez de Publicar. Todos os artigos gerados permanecerão no modo rascunho.
- Artigos rascunhos são visíveis no painel Categorias & Artigos do portal, mas não são acessíveis aos leitores no site da Base de Conhecimento.
- Você pode revisar, editar e adicionar conteúdo personalizado aos rascunhos dos artigos antes de publicar.
Categorias aninhadas
O Document360 suporta até três níveis de subcategorias no espaço de trabalho de documentação da API. As categorias são criadas com base nas definições de tags no seu arquivo de especificações.
Para criar categorias aninhadas, use o > símbolo nas tags do OpenAPI:
tags:
- name: "Pets > Details"
Isso cria uma Pets categoria com uma Details subcategoria dentro dela. Essa estrutura é preservada durante a ressincronização.
Se sua especialização definir mais de três níveis de aninhamento, quaisquer categorias além do terceiro nível são colocadas no terceiro nível.
Ordenação por categorias
A ordem em que as categorias aparecem na sua documentação corresponde à ordem de tags definida no seu arquivo de especificações. Para alterar a ordem das categorias, reordene o tags array na sua especificação e ressincronize.
Opções de categoria
Clicando com o botão direito em uma categoria no painel Categorias & Artigos, você oferece as seguintes opções:
| Opção | O que ele faz |
|---|---|
| Renomeação | Renomeie a categoria. |
| Artigo | Adicione um novo artigo ou subartigo dentro da categoria. |
| Subcategoria | Adicione uma subcategoria dentro da categoria. |
| Mudança de tipo | Mude o tipo de categoria. |
| Definir a pasta de drive | Vincule a categoria a uma pasta do Document360 Drive. |
| Editar referência da API | Atualize o arquivo de especificação ou URL para a referência da API. |
| Baixe a fonte original da API | Baixe o arquivo de especificações atual. |
| Publicar | Publique todos os artigos preliminares na categoria. |
| Segurança | Configure quem pode acessar a categoria pelo portal e pelo site da Base de Conhecimento. |
Você pode mover artigos de endpoint entre subpastas dentro da mesma pasta de referência de API. Não é possível mover um artigo de endpoint de uma pasta de referência de API para outra pasta de referência de API.
Atualização de conteúdo gerado por especificações via API
Artigos de endpoint gerados a partir de uma especificação de API (OpenAPI ou Swagger) são somente leitura pelos endpoints padrão da API de conteúdo, não podem ser recuperados ou atualizados dessa forma. Para modificar esse tipo de conteúdo:
- Atualize seu arquivo de definição de API (OpenAPI/Swagger).
- Resincronize a documentação usando o portal, CLI ou fluxo CI/CD para refletir as mudanças.
Isso mantém o conteúdo de referência do endpoint consistente com a especificação da sua API.
Artigos regulares de base de conhecimento, como páginas conceituais, guias de autenticação ou outros conteúdos não especificados, não estão vinculados à especificação da API. Eles podem ser criados, atualizados e gerenciados como qualquer outro conteúdo de base de conhecimento usando os endpoints padrão da API de conteúdo.
Se você receber um erro 403 ao tentar atualizar conteúdo via API, primeiro confirme com qual tipo de conteúdo está trabalhando. Se for conteúdo gerado por especificações, use o processo de resincronização acima em vez de ajustar as permissões dos tokens. Se for um artigo não especificado, veja tokens API para orientações sobre como revisar e atualizar permissões de tokens.
Se a edição colaborativa estiver ativada no seu projeto, múltiplos colaboradores podem editar esses artigos não especificados ao mesmo tempo, assim como nos artigos normais da base de conhecimento. Isso não se aplica a artigos endpoint gerados por especificação, que só podem ser editados dentro de seus blocos de conteúdo personalizados.
A edição colaborativa é implementada em fases, então se você ainda não a vê, está a caminho.
FAQ
Com que frequência uma referência de API é ressincronizada automaticamente?
Referências de API criadas a partir de uma URL ou arquivo não são ressincronizadas automaticamente. Elas devem ser atualizadas manualmente pelo portal. Para habilitar atualizações automáticas, integre ao fluxo CI/CD.
Posso mover um artigo específico sobre endpoint de API de uma pasta de referência de API para outra?
Não. Você pode mover artigos de endpoint entre subpastas dentro da mesma pasta de referência de API, mas não entre pastas de referência de API diferentes.
Um artigo de documentação de API pode ter a mesma URL que um artigo de Knowledge Base?
Não. Artigos de documentação de API e artigos do Knowledge Base não podem compartilhar a mesma URL. No entanto, eles podem existir sob o mesmo subdomínio.
Posso manter a documentação gerada no modo rascunho?
Sim. Após enviar uma especificação, clique em Fechar em vez de Publicar na janela de confirmação. Todos os artigos gerados serão salvos no modo rascunho.
Quantos níveis de categorias são suportados?
O espaço de trabalho de documentação da API suporta até três níveis de subcategorias. Níveis adicionais são reprimidos para o terceiro nível.
Posso criar pastas aninhadas automaticamente a partir do arquivo de especificações?
Sim, usando o > símbolo nas tags OpenAPI (por exemplo Pets > Details, ). Isso cria uma estrutura hierárquica que é preservada durante a resincronização.
Os leitores podem acessar o site da base de conhecimento durante o período de inatividade do portal Document360?
Sim. As chamadas GET da API do Cliente rodam independentemente do portal Document360, para que os leitores possam continuar acessando o site durante manutenção programada ou tempo de inatividade do portal.