O recurso 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 uma documentação polida e interativa para desenvolvedores, sem exigir ferramentas personalizadas ou formatação manual.
A experiência do leitor
Quando você publica uma referência de API, os desenvolvedores acabam em uma página interativa de três painéis — não um documento estático. Entender esse layout ajuda você a imaginar o que seus leitores realmente veem e indica o artigo que explica cada parte em detalhe.
- Esquerda - árvore de navegação. Cada endpoint na sua especificação, agrupado por tag em categorias e subcategorias, com um rótulo de método (GET, POST, PUT, PATCH, DELETE) ao lado de cada um. Os leitores filtram por nome para pular rapidamente para um endpoint.
- Centro - documentação. A descrição do endpoint, os parâmetros de caminho e consulta, o esquema do corpo da requisição e os requisitos de autenticação – tudo gerado a partir da sua especificação.
- Certo - Painéis de Código e Resposta. Exemplos de pedidos prontos para uso e respostas de exemplo, lado a lado com a documentação.
Painel de códigos
O painel de Código mostra um exemplo de solicitação pronta para copiar para o endpoint, e os leitores podem mudar a linguagem para corresponder à sua pilha. Seis idiomas estão disponíveis:
- cURL
- Shell
- Python
- Java
- JavaScript
- C#
Cada exemplo é atualizado para refletir o caminho real do endpoint, os parâmetros e a autenticação, para que o leitor possa copiá-lo diretamente para seu próprio ambiente.
Painel de resposta
O painel de Resposta mostra respostas de exemplo para o endpoint, organizadas por código de status (por exemplo, respostas de sucesso e erro como 200, 401, 403, 404, 422, 429, 500). Os leitores selecionam um código de status para ver a forma da resposta que devem esperar em cada caso, o que facilita o tratamento tanto do sucesso quanto dos caminhos de erro em sua integração.
Tente
Try It transforma a referência de algo que os leitores leram em algo que eles podem rodar. Ele abre um console interativo em linha em qualquer endpoint, para que os desenvolvedores possam enviar uma solicitação real e ver a resposta ao vivo - status, tempo, cabeçalhos e corpo - sem sair da página ou escrever qualquer código. Veja Testando endpoints com Try it! para o guia completo.
Autenticação
Os leitores fornecem credenciais diretamente no console Try It, usando o esquema definido pela sua API — chave API, HTTP Basic, HTTP Bearer, OAuth 2.0 ou OpenID Connect. O Try It lê os esquemas da sua especificação e mostra os campos corretos para cada um. Veja Autorizar solicitações no console Try It para detalhes sobre cada método.
Variáveis
Variáveis permitem que os leitores armazenem um valor uma vez, como um ID ou um token, e o reutilizem em todos os pontos finais da referência com um {{placeholder}}. Isso evita a redigitação de valores comuns à medida que eles se movem de um ponto final para o outro. Veja Usando variáveis no console Try It.
IA Eddy
A Eddy AI está embutida na referência para que os leitores possam fazer perguntas sobre um endpoint – como ele funciona, como autenticar, ou para um exemplo de código em uma linguagem específica e obter respostas sem sair da página. Veja Usar Eddy AI na referência da API.
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 a autenticação funciona. Ao contrário dos artigos da base de conhecimento geral, os documentos da API seguem um formato estruturado e rigoroso derivado de um arquivo de especificação legível por máquina.
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 de API vs documentação regular
| Aspecto | Documentação da API | Documentação regular |
|---|---|---|
| Público principal | Desenvolvedores e integradores técnicos | Usuários finais, equipes internas |
| Estrutura | Impulsionado por um arquivo de especificação (OpenAPI, Postman) | Artigos escritos manualmente |
| Tipo de conteúdo | Endpoints, parâmetros, esquemas, métodos de autenticação | Guias, tutoriais e artigos conceituais |
| Interatividade | Testes ao vivo via Try It! | Leitura estática |
| Versionamento | Vinculado às versões da API | Gerenciado editorialmente |
| Geração automática | Sim, do arquivo de especificações | Não |
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. Para uma referência completa de todos os endpoints e esquemas disponíveis, veja a documentação do desenvolvedor do Document360.
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.
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.
Webhooks 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. Try It! não está disponível para webhooks. Webhooks são suportados para upload de arquivos, importação de URLs e fluxos CI/CD.
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. O Document360 suporta os seguintes métodos de autorização:
- Autenticação básica - Requer um nome de usuário e senha passados na solicitação.
- Token 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: Código de Autorização, PKCE, Credenciais do Cliente e Implícito.
- OpenID Connect - Estende o OAuth2 adicionando verificação de identidade de usuário.
Para autenticar requisições na API de Cliente do Document360, você precisará de um token de API. Para mais informações, veja o artigo sobre tokens de API .
Para fazer sua primeira solicitação API autenticada usando Swagger, Postman ou curl, consulte Making your first request.
OAuth2 e OpenID Connect: configuração adicional
Ao trabalhar com APIs que usam OAuth2 ou OpenID Connect, são necessárias duas configurações para que o Try It! funcione corretamente:
- URI de redirecionamento - Defina isso no seu provedor OAuth para a URL de retorno OAuth da referência da API:
https://<your-knowledge-base-domain>/assets/apidocs-oauth-callback.html. - Renovação silenciosa - O Document360 atualiza automaticamente o token de autorização em segundo plano durante sessões ativas do Try It!, então os usuários não precisam se autenticar manualmente.
FAQ
O que é uma referência de API?
Uma referência de API é um recurso documental que fornece informações abrangentes sobre as funções, classes, métodos, parâmetros, tipos de retorno e outros componentes de uma API. É um guia ou manual para desenvolvedores que desejam integrar ou usar a API em suas aplicações.
Quantas referências de API posso criar?
Dentro de cada espaço de trabalho de API, você pode criar no máximo 3 referências de API.
Qual é a ordem padrão das categorias ao fazer upload de um arquivo de especificação do OpenAPI?
As categorias no Document360 são criadas com base na ordem de tags definida no seu arquivo de especificações. Por exemplo, se sua especificação definir tags na ordem Pet, Loja, Usuário — as categorias aparecerão na mesma ordem.
A opção "Experimente!" não está disponível no site da Knowledge Base. Qual poderia ser o motivo?
Se o recurso Experimente! não estiver visível, certifique-se de que tanto a variável do servidor quanto a URL do servidor estejam devidamente definidas no seu arquivo de especificação da API. Sem esses, o recurso não funcionará.
Os valores do menu suspenso de referência da API podem ser modificados através da interface?
Não. Alterações em elementos de referência da API, como valores suspensos, só podem ser feitas através do arquivo de especificação OpenAPI. Modificar esses valores pela interface atualmente não é suportado.