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 uma documentação polida e interativa para desenvolvedores, sem exigir ferramentas personalizadas ou formatação manual.
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.
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.
O recurso Try It! no Document360 permite que você teste endpoints da API diretamente no site da Knowledge Base. O console interativo permite que desenvolvedores insiram os parâmetros necessários e executem chamadas de API, obtendo respostas em tempo real, sem sair da documentação ou escrever qualquer código.
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 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.
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:
- Redirecionar URI - Defina isso no seu provedor OAuth para o formato
domain/oauth. Por exemplo:https://apidocs.document360.com/oauth. - 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
Como a documentação da API é diferente da documentação comum?
A documentação da API é especificamente projetada para explicar endpoints, autenticação e integrações. É separado dos artigos padrão da base de conhecimento e útil para conteúdo voltado para desenvolvedores.
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.
Quais são os formatos de arquivo de especificação suportados?
Você pode enviar seu arquivo de especificação como URL, JSON, YML ou YML . O Document360 suporta especificações OpenAPI 2.0, OpenAPI 3.0, OpenAPI 3.1 e Postman.
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.
Vídeos relacionados
Experimente nossa documentação moderna de API no Document360
Teste endpoints da API diretamente da documentação com o Try It!
Informações adicionais
Leia nosso blog sobre - Apresentando a Documentação da API: Aprimore sua Experiência na API