Introdução à documentação da API

Planos que suportam a documentação da API

O recurso de documentação API no Document360 fornece uma solução completa para criar e gerenciar referências de API. Esse recurso permite gerar documentação de API de alta qualidade que ajuda os usuários a entender e trabalhar com suas APIs de forma eficaz. Você pode gerar essa documentação carregando o arquivo de especificação da API de uma URL, um arquivo JSON/YAML/YML ou integrando-se a um fluxo de CI/CD.

Além disso, o recurso Experimentar! no Document360 permite testar endpoints de API diretamente no Knowledge base site. O console interativo no site da base de conhecimento permite que os desenvolvedores insiram os parâmetros necessários e executem chamadas de API, obtendo respostas em tempo real. Esse recurso é útil para solucionar problemas e entender como uma API se comporta sem sair da documentação ou escrever nenhum código.

Integração da documentação da API

Ao se inscrever no Document360, os usuários escolhem seu caso de uso principal na Etapa 1 do fluxo de integração. Para usuários que desejam criar documentação de API, o Document360 oferece uma experiência de integração simplificada. Se você selecionar a documentação da API como seu caso de uso, será redirecionado para o fluxo de configuração da API, onde poderá criar referências de API usando as opções disponíveis.

Na Etapa 2 do fluxo de integração, você terá três opções para criar uma referência de API:

• Carregar arquivo de API: Suporta arquivos JSON/YAML/YML (coleções OpenAPI 2.0, OpenAPI 3.0, OpenAPI 3.1 e Postman).

• Criar a partir do URL: busca automaticamente a especificação da API do URL hospedado.

• Experimente um arquivo de API de loja de animais de estimação: se você não tiver um arquivo de API pronto, poderá usar o arquivo de exemplo (API de loja de animais) oferecido pelo Document360 para preencher seu espaço de trabalho.

Carregando um arquivo de definição de API

Para criar uma referência de API a partir de um arquivo de definição de API, selecione o botão de opção Carregar arquivo de API. Em seguida, clique em Carregar do meu dispositivo ou arraste e solte o arquivo de especificação da API do seu dispositivo.

NOTA

Os formatos de arquivo compatíveis com o arquivo de definição de API são JSON, YAML ou YML.

O sistema analisará o arquivo e gerará a referência da API automaticamente.

• Seum y alertas/avisos forem detectados no arquivo carregado, uma visão geral de alto nível será exibida durante a integração. Você pode exibir detalhes detalhados no portal da base de dados de conhecimento na seção de logs em Mais opções nas referências de API.

• Se algum erro for detectado no arquivo carregado (por exemplo, - Formato de arquivo não suportado), substitua o arquivo carregado por um arquivo alternativo.

Inserindo uma URL de documentação da API

Para criar uma referência de API a partir de uma URL de documentação da API, selecione o botão de opção Criar a partir da URL . Em seguida, insira a URL do arquivo OpenAPI no campo URL para a definição da API . O Document360 buscará e processará a estrutura da API. Semelhante aos uploads de arquivos,

• Se algum alerta/aviso for detectadod, você poderá exibi-lo no portal da base de dados de conhecimento na seção de logs em Mais opções nas referências de API.

• Se algum erro for detectado (por exemplo, URL inválido), insira o URL válido para o arquivo OpenAPI.

Ignorando a configuração da API

Se você escolher a opção Experimentar arquivo de API de loja de animais de amostra ,

• O Document360 criará automaticamente uma referência de API de amostra (API da loja de animais).

• Isso estará disponível no modo de rascunho. Você pode revisar os pontos de extremidade antes de publicar ou carregar seu arquivo de especificação e publicá-lo mais tarde.

Personalize sua base de conhecimento

Na Etapa 3, você pode inserir o URL do seu site preferido. Se você quiser pular esta etapa, o domínio será padronizado para aquele vinculado ao seu e-mail de registro.

Diretrizes da marca

Na Etapa 4, o nome do projeto, o idioma padrão, o logotipo da marca e as cores da marca são definidos automaticamente com base no URL fornecido. No entanto, você pode editar esses campos, se necessário. As configurações de idioma do seu navegador determinam o idioma padrão. O inglês será selecionado por padrão se outros idiomas não suportarem o idioma do seu navegador.

NOTA

• Se você escolher Espanhol ou Português do Brasil como idioma padrão, o idioma do portal será definido como Espanhol ou Português do Brasil. Caso contrário, o inglês será o idioma padrão.

• O logotipo da marca e as cores primárias/secundárias são extraídos do seu site. Se você optar por Ignorar esta etapa, o nome do projeto será derivado do seu e-mail de registro e o logotipo e as cores padrão do Document360 serão aplicados.

Definir a privacidade da documentação

Na Etapa 5, você pode escolher as configurações de privacidade desejadas para o seu site:

• Privado: Restrinja o acesso à base de conhecimento para que apenas contas de equipe possam visualizar e interagir com o conteúdo, mantendo-o seguro e interno.

• Público: Torne a base de conhecimento acessível a todos, incluindo usuários externos, permitindo acesso aberto a todo o conteúdo.

• Misto: combine o acesso privado e público, permitindo que algumas seções da base de conhecimento fiquem visíveis ao público, mantendo outras seções restritas apenas às contas da equipe.

Por fim, clique em Avançar para concluir o fluxo de integração da API.

Você será redirecionado para o espaço de trabalho de documentação da API, onde:

• Você verá a referência da API da especificação da API fornecida durante a integração.

• Se você não forneceu uma especificação de API, uma referência de API de amostra (API de loja de animais) estará disponível no modo de rascunho.  

Técnicas de autorização

Ao interagir com uma API, é importante garantir que apenas usuários autorizados possam acessar determinados dados ou executar ações específicas. Isso é feito usando técnicas de autorização, que controlam o acesso e as permissões. O Document360 oferece suporte a vários métodos de autorização para proteger sua API, incluindo:

• Autenticação básica: requer um nome de usuário e senha passados na solicitação.

• Token de portador: autentica-se com um token gerado após o login.

• Chave de API: usa uma chave exclusiva, passada nos cabeçalhos da solicitação, para autenticação.

• OAuth2: protege as APIs por meio de vários fluxos, como código de autorização, PKCE, credenciais do cliente e fluxos implícitos.

• OpenID Connect: estende o OAuth2 adicionando a verificação de identidade do usuário.

Considerações sobre autorização (OAuth2 e OpenID)

Ao trabalhar com APIs que usam OAuth2 ou OpenID para autorização, certas configurações são essenciais para a funcionalidade adequada.

• URI de redirecionamento: essa é a URL para a qual o usuário será redirecionado após concluir um fluxo de autorização. Certifique-se de definir o URI no formato: domain/oauth. Por exemplo: https://apidocs.document360.com/oauth.

• Renovação silenciosa: a renovação silenciosa atualiza automaticamente o token de autorização em segundo plano, para que os usuários não precisem se autenticar novamente durante a sessão. Isso mantém a sessão ativa sem interrupção. Para evitar que a autorização expire durante as sessões em que os usuários interagem com o recurso Experimentar! , o Document360 renova automaticamente o token de atualização em segundo plano. Isso garante que os usuários não precisem se autenticar novamente manualmente.

Compra

Você terá acesso a 1 espaço de trabalho de API como parte de todos os planos pagos do Document360 (Professional, Business e Enterprise). Se você quiser comprar espaços de trabalho de API adicionais,

1. Navegue até Configurações() > Portal da base de conhecimento > Faturamento > Meu plano.

2. Clique em Comprar complemento.

3. Adicione o número desejado de espaços de trabalho de documentação de API. Revise o custo do complemento e o valor devido.

4. Clique em Confirmar pagamento para prosseguir com o pagamento.

Solucionando problemas

Problemas de acesso à API

Erro: erro 400 – o acesso à API está desabilitado. Entre em contato com o administrador do projeto.

Esse erro ocorre quando o acesso público à API é desativado nas configurações do projeto.

Etapas para resolver:

1. Navegue até Configurações() > recursos de IA > Eddy AI no portal da base de conhecimento.

2. Na seção AI search suite , verifique se a caixa de seleção API pública está marcada.

   

3. 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

Vídeos relacionados

Experimente nossa moderna documentação de API no Document360 como nunca antes

Testar endpoints de API diretamente da documentação com o recurso Try it

Informações adicionais

Apresentando a documentação da API: aprimore sua experiência de API - Clique para ler