Este guia guia você na publicação da sua primeira referência de API no Document360, desde o upload do seu arquivo especulativo até um portal interativo e ao vivo para desenvolvedores.
Ao final deste artigo, você terá:
- Uma referência de API gerada a partir da sua especificação OpenAPI
- Seus endpoints visíveis e navegáveis pelos desenvolvedores
- O console interativo Try It! pronto para testes ao vivo da API
A documentação da API está disponível em todos os planos pagos. Cada plano pago inclui um espaço de trabalho da API. Espaços de trabalho adicionais podem ser adquiridos como complementos.
Pré-requisitos
Antes de começar, certifique-se de ter:
- Uma conta Document360 em um plano Profissional, Empresarial ou Empresarial.
- Um arquivo de especificação de API em um desses formatos: OpenAPI 2.0, OpenAPI 3.0, OpenAPI 3.1 ou Postman Collection. Os tipos de arquivo aceitos são JSON, YML ou YML.
- Acesso ao portal da Base de Conhecimento com permissões para criar conteúdo.
Se você ainda não tem um arquivo de especificações, ainda pode seguir este guia usando o arquivo API de Pet Store de exemplo que o Document360 fornece. Você será solicitado a usá-lo durante a configuração.
Navegue até o espaço de trabalho de documentação da API
- Faça login no Document360 e abra seu projeto no portal da Base de Conhecimento.
- Na barra de navegação da esquerda, clique em documentação
{ }da API. Isso abre o espaço de trabalho dedicado da API, separado da sua base de conhecimento padrão. - Na barra de navegação superior, clique no menu suspenso Criar e selecione Nova API. Isso abre a janela de referência da Nova API.
Você pode criar no máximo 3 referências de API dentro de cada workspace de API.
Escolha como importar sua especificação
O Document360 suporta duas formas de importar seu arquivo de especificações: upload de arquivos e importação de URL. O fluxo CI/CD não é um método de importação separado; É uma forma de automatizar qualquer um desses dois métodos para que sua documentação seja atualizada automaticamente sempre que sua especificação mudar.
| Método | Quando usá-lo | Como funciona |
|---|---|---|
| Upload do arquivo | Você tem o arquivo de especificação localmente como JSON, YAML ou YML. | Envie o arquivo diretamente. É melhor para começar rápido ou para atualizações esporádicas. |
| Importação de URL | Sua especificação está hospedada em uma URL pública ou interna estável. | Aponte o Document360 para a URL. Você pode resincronizar manualmente a partir da mesma URL sempre que a especificação mudar. |
| Fluxo CI/CD | Você quer que a documentação seja atualizada automaticamente a cada mudança de especificação. | Automatiza o upload de arquivos ou a importação de URL via a CLI d360 no seu pipeline. Exige Node.js. |
Faça upload da sua especificação
Faça upload de um arquivo
- Na janela de referência da Nova API, selecione a opção Definir a API de Upload .
- Clique em Upload do meu dispositivo ou arraste e solte seu arquivo. Formatos suportados: JSON, YAML, YML.
- O Document360 analisa o arquivo e gera automaticamente a referência da API. Se avisos forem detectados, aparece uma seção de Alertas e Avisos — amplie-a para revisá-los. Você pode ver todos os detalhes mais adiante na seção de Registros.
- Clique em Nova referência de API para prosseguir.
Importar a partir de uma URL
- Na janela de referência da Nova API, selecione a opção Criar a partir da URL e clique em Próximo.
- Insira a URL apontando para o seu arquivo de especificação OpenAPI no campo URL.
- O Document360 busca e processa a especificação. Se avisos forem detectados, eles estarão disponíveis na seção de Logs após a importação.
- Clique em Adicionar referência de API para prosseguir.
Use o fluxo CI/CD
Essa opção exige que Node.js seja instalado no seu sistema.
- Na janela de referência da Nova API, selecione a opção CI/CD Flow .
- Copie o comando completo da CLI mostrado na janela.
- No comando copiado, substitua o
--pathvalor pelo caminho completo para seu arquivo de especificação local ou por uma URL válida apontando para ele. Por exemplo:
--path=/Users/yourname/projects/api/openapi.yaml
Ou uma URL:
--path=https://example.com/api/openapi.yaml
- Cole o comando atualizado no seu terminal e pressione Enter. O Document360 faz upload da sua especificação e gera a documentação da API.
A primeira linha do comando CLI (npm install d360 -g) instala a ferramenta CLI Document360. Você só precisa rodar uma vez. Se já estiver instalado, você pode pular essa linha.
Se você regenerar sua chave API, deve atualizar o --apiKey valor no comando CLI antes de executá-lo novamente. A chave antiga não será mais válida.
Sem arquivo de especificações? Use a API de Pet Store de exemplo
Se você não tiver um arquivo de especificação pronto, selecione Tentar o arquivo API da Pet Store de exemplo quando solicitado. O Document360 criará automaticamente uma referência de API de exemplo no modo rascunho. Você pode explorar e depois substituir por sua própria especialização.
Avisos e alertas de revisão
Após enviar sua especificação, o Document360 mostra um resumo de quantas categorias e artigos foram criados, junto com quaisquer alertas ou alertas detectados no seu arquivo.
- Alertas e alertas significam que a especificação foi importada, mas alguns elementos podem não aparecer como esperado. Você pode consultar todos os detalhes na seção de Logs: vá até a referência da sua API, clique no ícone Mais
(⋯)e selecione Logs. - Erros significam que a importação falhou. A causa mais comum é um formato de arquivo não suportado ou uma URL inválida. Substitua o arquivo ou corrija a URL e tente novamente.
Publique sua referência de API
Depois que sua especificação for processada com sucesso:
- Uma janela de confirmação mostra o número de categorias e artigos criados. Clique em Publicar para ativar a referência da API.
- Se quiser revisar o conteúdo antes de publicar, clique em Fechar. Sua referência de API é salva no modo rascunho e visível no painel Categorias & Artigos.
O modo rascunho é útil se você quiser adicionar conteúdo personalizado a artigos endpoint individuais antes de torná-los públicos. Qualquer conteúdo personalizado que você adicionar será mantido quando você regenerar ou ressincronizar sua documentação.
Configure a autenticação para o Try It!
O console Try It! permite que os desenvolvedores testem seus endpoints de API diretamente pela documentação. Para que funcione corretamente, o método de autenticação deve estar definido na sua especificação e configurado no Document360.
O Document360 suporta os seguintes métodos de autenticação:
| Método | Como funciona |
|---|---|
| Autenticação básica | Nome de usuário e senha passados no cabeçalho da solicitação. |
| Token de portador | Um token gerado após o login, passado pelo cabeçalho de Autorização. |
| Chave API | Uma chave única era passada nos cabeçalhos de requisição. |
| OAuth2 | Suporta Código de Autorização, PKCE, Credenciais do Cliente e fluxos implícitos. |
| OpenID Connect | Estende o OAuth2 para adicionar verificação de identidade de usuário. |
O console Try It! suporta múltiplos esquemas de segurança simultaneamente, permitindo testar endpoints que exigem métodos de autenticação combinados.
OAuth2 e OpenID Connect: configuração adicional
Ao usar OAuth2 ou OpenID Connect, são necessárias duas configurações:
- Redirecionar URI — Defina isso no seu provedor OAuth para
domain/oauth. Por exemplo:https://apidocs.yourdomain.com/oauth. - Renovação silenciosa — O Document360 atualiza automaticamente o token de autorização em segundo plano durante sessões ativas do Try It!, para que os usuários não precisem se autenticar manualmente.
Se o botão Experimente! não estiver visível no seu site da Knowledge Base, verifique se tanto a variável do servidor quanto a URL do servidor estão corretamente definidas no seu arquivo de especificação da API. Sem esses, o recurso Experimente! não vai funcionar.
Definir acesso e privacidade do leitor
Controle quem pode ver sua referência de API publicada configurando as configurações de acesso ao leitor.
| Ambientação | O que isso significa |
|---|---|
| Privado | Apenas as contas da equipe podem visualizar a referência da API. Use para APIs internas ou apenas para parceiros. |
| Público | Qualquer pessoa pode acessar a referência da API sem autenticação. |
| Misto | Algumas seções são públicas, outras restritas às contas de equipe. |
Para configurar o acesso do leitor, navegue até Configurações > Usuários e Permissões > Acesso ao Leitor no portal da Base de Conhecimento e localize o espaço de trabalho da documentação da sua API.
Visitar /apidocs antes da publicação de qualquer artigo endpoint retornará um erro 404 — ainda não há conteúdo para exibir. Isso também se aplica se você adicionou um link /apidocs de navegação no seu site da base de conhecimento. Publique pelo menos um artigo sobre endpoint antes de tornar sua referência de API acessível aos leitores.