Começando com a documentação da API

Visão geral

O recurso de documentação de API do Document360 oferece uma solução completa e completa para publicar, gerenciar e testar referências de API. Seja você uma startup lançando sua primeira API pública ou uma empresa mantendo dezenas de microserviços internos, o Document360 transforma sua especificação OpenAPI em documentação polida e interativa para desenvolvedores, sem exigir ferramentas personalizadas ou formatação manual.

Este artigo cobre tudo o que você precisa saber: configurar sua primeira referência de API, escolher o método certo de importação, proteger endpoints com autenticação, testar ao vivo com o Try It!, lidar com webhooks, rodar pipelines integrados CI/CD e seguir as melhores práticas que separam bons documentos de API de realmente excelentes.

O que é documentação de API e por que isso importa?

A documentação da API é a referência técnica que diz aos desenvolvedores exatamente como interagir com sua API: quais endpoints existem, quais parâmetros eles aceitam, quais respostas retornam e como funciona a autenticação. Diferente dos artigos do banco de conhecimento geral, os documentos da API seguem um formato rígido e estruturado derivado de um arquivo de especificação legível por máquina (como o OpenAPI).

Por que isso importa:

• Reduz o tempo de integração. Documentos claros reduzem o onboarding de dias para horas. Os desenvolvedores gastam menos tempo adivinhando e mais tempo construindo.

• Reduz a carga de suporte. Quando os documentos respondem às perguntas "como autentico?" e "o que significa um 422?", sua equipe recebe menos tickets.

• Constrói confiança entre desenvolvedores. Documentos da API incompletos ou desatualizados sinalizam um produto pouco confiável. Documentação de alta qualidade é um sinal direto da qualidade do produto.

• Permite o autoatendimento. Parceiros externos, clientes e desenvolvedores terceirizados podem se integrar sem precisar de apoio da sua equipe.

Documentação da API vs. documentação regular

No Document360, a documentação da API está em um espaço de trabalho dedicado da API, separado da sua base de conhecimento padrão. Isso permite diferentes controles de acesso, roteamento e branding para seu conteúdo voltado para desenvolvedores.

Formatos de especificação suportados

O Document360 suporta os seguintes formatos de especificação:

• OpenAPI 2.0 (anteriormente Swagger)

• OpenAPI 3.0

• OpenAPI 3.1 (inclui suporte a webhooks)

• Coleções do Carteiro

Os arquivos podem ser enviados como JSON, YML ou YML.

Escolhendo um formato: Se você está começando do zero, use a OpenAPI 3.1. É o padrão atual, suporta webhooks nativamente e tem o ecossistema de ferramentas mais rico. Se você está migrando de uma configuração Swagger 2.0 existente, o Document360 aceita como está enquanto você faz upgrade incrementalmente.

Além disso, o recurso Experimente! no Document360 permite testar endpoints da API diretamente no Knowledge base site. O console interativo no site da Knowledge base permitirá 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 código.

NOTA

A seção Experimente! suporta múltiplos esquemas de segurança simultaneamente, permitindo que os usuários testem endpoints que exigem métodos de autenticação combinados de forma mais eficaz.

Webhooks (eventos) no OpenAPI 3.1

O Document360 suporta webhooks definidos no OpenAPI 3.1. Webhooks aparecem com um ícone de evento na referência da sua API e incluem uma seção de payload baseada no seu esquema. Se nenhum exemplo for fornecido, o Document360 mostra um exemplo padrão e uma carga útil de exemplo. Tente, não está disponível para webhooks. Webhooks são suportados para upload de arquivos, importação de URLs e fluxos CI/CD.

Integração de documentação da API

Ao se cadastrar 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 mais ágil. Se você selecionar a documentação da API como seu caso de uso, será redirecionado para o fluxo de configuração da API, onde pode criar referências de API usando as opções disponíveis.

No Passo 2 do fluxo de onboarding, você terá três opções para criar uma referência de API:

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

• Criar a partir da URL: Obtém automaticamente a especificação da API da URL hospedada.

• Tente um arquivo API de loja de animais de estimação: Se você não tiver um arquivo de API pronto, pode usar o arquivo de exemplo (API da loja de animais) oferecido pelo Document360 para preencher seu espaço de trabalho.

Enviando 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 Upload de arquivo API. Em seguida, clique em Enviar do meu dispositivo ou arraste e solte seu arquivo de especificação da API do seu dispositivo.

NOTA

Os formatos de arquivo suportados para o arquivo de definição de API são JSON, YAML ou YML.

O sistema analisa o arquivo e gera a referência da API automaticamente.

• Se algum alerta/alerta for detectado no arquivo enviado, uma visão geral de alto nível será exibida durante a integração. Você pode ver detalhes detalhados no portal da base de conhecimento, na seção de logs, em Mais opções dentro de referências da API.

• Se algum erro for detectado no arquivo enviado (por exemplo, formato de arquivo não suportado), substitua o arquivo enviado 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 seu arquivo OpenAPI na URL do campo de definição da API . O Document360 irá buscar e processar a estrutura da API. Semelhante ao upload de arquivos,

• Se algum alerta/alerta for detectado, você pode visualizá-los no portal da base de conhecimento, na seção de logs, em Mais opções dentro de referências da API. Você pode ver detalhes detalhados no portal da base de conhecimento, na seção de logs, em Mais opções dentro de referências da API.

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

Pulando a configuração da API

Se você escolher a opção Tentar o arquivo API da loja de animais de exemplo ,

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

• Estará disponível no modo draft. Você pode revisar os endpoints antes de publicar ou enviar seu arquivo de especificação e publicá-lo depois.

Personalize sua base de conhecimento

No Passo 3, você pode inserir a URL do seu site preferido. Se você quiser pular essa etapa, o domínio será o padrão vinculado ao seu e-mail de registro.

Diretrizes de marca

No Passo 4, o nome do seu projeto, idioma padrão, logo da marca e cores da marca são definidos automaticamente com base na URL fornecida. 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 brasileiro como idioma padrão, o idioma do portal será definido para espanhol ou português brasileiro. Caso contrário, o inglês será o idioma padrão.

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

Definir privacidade documental

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

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

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

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

Por fim, clique em Próximo para completar 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 que você forneceu durante a integração.

• Se você não forneceu uma especificação de API, uma referência de API de exemplo (Pet Store API) estará disponível em modo rascunho.  

Técnicas de autorização

Ao interagir com uma API, é importante garantir que apenas usuários autorizados possam acessar certos dados ou realizar ações específicas. Isso é feito usando técnicas de autorização, que controlam acesso e permissões. O Document360 suporta 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 com um token gerado após o login.

• Chave API: Usa uma chave única, passada nos cabeçalhos da requisição, para autenticação.

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

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

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

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

• URI de redirecionamento: Esta é a URL para a qual o usuário será redirecionado após completar 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 reautenticar durante a sessão. Isso mantém a sessão ativa sem interrupções. Para evitar que a autorização expire durante sessões em que os usuários interajam com o recurso Experimente! , o Document360 renova automaticamente o token de atualização em segundo plano. Isso garante que os usuários não precisarão se reautenticar manualmente.

Compras

Você terá acesso a 1 espaço de trabalho API como parte de todos os planos pagos do Document360 (Profissional, Empresarial e Empresarial). Se você deseja adquirir espaços de trabalho adicionais para API,

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

2. Clique no complemento Comprar.

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

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

Solução de problemas

Problemas de acesso à API

Erro: erro 400 – Acesso à API desativado. Por favor, entre em contato com o administrador do seu projeto.

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

Passos para resolver:

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

2. Na seção de suíte de busca de IA , certifique-se de que a caixa de seleção da API Pública esteja selecionada.

   

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

Problemas de importação de API

Erro: Formato inválido – Falha no upload do arquivo API.

Esse erro ocorre quando uma ou mais respostas no arquivo de especificação do OpenAPI estão faltando a seção necessária content .

Embora o arquivo possa passar pela validação no Swagger Editor, o Document360 aplica regras rigorosas de validação OpenAPI e exige que todas as respostas definam explicitamente o tipo de mídia (por exemplo, application/json) e a referência do esquema.

Passos para resolver:

1. Abra seu arquivo de especificação OpenAPI (Swagger) em um editor de texto ou IDE.

2. Localize quaisquer definições de resposta que estejam vazias ou que referenciam diretamente um esquema sem bloco content .

   Exemplo de resposta incorreta:

   responses:
     "200": {}

3. Atualize a definição de resposta para incluir uma seção de conteúdo com o tipo de mídia e referência de esquema apropriados.

   Exemplo de resposta correta:

   responses:
     "200":
       description: OK
       content:
         application/json:
           schema:
             $ref: "#/components/schemas/UserGroupFetchResponse"

4. Salve o arquivo e tente enviá-lo novamente para o Document360.

Resumo e Tags não refletidos após a importação de uma especificação de API

Erro: Os endpoints importados não exibem os títulos corretos nem aparecem nas pastas de tags esperadas.

Esse problema ocorre quando os summary campos e tags na especificação OpenAPI são definidos no nível do caminho, em vez de sob o objeto de operação (get, post, put, ou delete).

Além disso, o tags campo deve sempre ser escrito como um array, mesmo quando apenas uma tag é usada.

Passos para resolver:

1. Abra seu arquivo de especificação OpenAPI em um editor de texto.

2. Mova os campos de resumo e tags dentro de cada objeto de operação.

3. Certifique-se de que o valor da tag seja escrito como um array.

   Exemplo incorreto:

   /dms/modules/{module-name}/types/logical/{logical-type}:
     summary: Type & Logical type
     tags: Logical Types
     get:
       ...
   

   Exemplo correto:

   /dms/modules/{module-name}/types/logical/{logical-type}:
     get:
       summary: Type & Logical type
       tags: ["Logical Types"]
       ...
   

4. Após fazer essas atualizações, salve o arquivo e reimporte para o Document360.

   Os artigos importados agora usarão o summary valor como título do artigo, e pastas baseadas em tags serão criadas corretamente.

A página inicial da base de conhecimento redireciona para  /apidocs após a atualização da conta

Erro: A página inicial da base de conhecimento redireciona para  /apidocs e a página não existe

Esse problema ocorre quando um espaço de trabalho de documentação da API está configurado como acesso público ao leitor.

Quando a base de conhecimento é atualizada, o espaço de trabalho de documentação da API pode ser configurado para acesso público ao leitor. Como resultado, os visitantes da página inicial da base de conhecimento são automaticamente redirecionados para a /apidocs página, que não é criada por padrão.

Passos para resolver:

1. Navegue até Configurações () > Usuários e Permissões na barra de navegação à esquerda do portal da Base de Conhecimento.

2. No painel de navegação esquerdo, navegue até o acesso ao Leitor.

3. Localize o espaço de trabalho de documentação da API.

4. Defina o acesso do leitor como Privado.

Isso vai impedir o redirecionamento não intencional e restaurar o acesso normal à página inicial da sua base de conhecimento.

Vídeos relacionados

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

Endpoints da API de teste diretamente da Documentação com o recurso Testar

Informações adicionais

Apresentando a Documentação da API: Aprimore sua Experiência na API - Clique para ler