Ao abrir um documento de API online publicado usando o Apidog, você notará um botão "Try it" (Experimentar) ao lado de cada endpoint. Clicar nele exibe um painel de depuração no lado direito da página, permitindo que você teste a API diretamente na documentação.
No entanto, a usabilidade desse recurso de "Depuração" depende em grande parte de quão bem você o configurou na plataforma. Fatores como a configuração adequada da URL, a configuração de autenticação, uma estrutura clara de parâmetros e dados de exemplo completos impactam significativamente a experiência de depuração.
Se não for configurado corretamente, os usuários podem gastar muito tempo preenchendo parâmetros ou até mesmo falhar ao fazer chamadas de API bem-sucedidas, o que está longe do ideal.
Vamos discutir como configurar o Apidog de forma eficaz para garantir que a documentação online publicada forneça uma excelente experiência de depuração.
Configuração Adequada da URL
Muitas vezes, a documentação online parece boa, mas falha quando você clica no botão "Try it" para enviar uma solicitação. A razão mais comum é que o endpoint inclui apenas um caminho como /pet/{petId} sem selecionar um ambiente de execução durante a publicação.
Isso resulta em URLs de solicitação incompletas, sem protocolo ou nome de host, levando a erros ao enviar solicitações.
Para resolver isso, certifique-se de que os usuários possam acessar a URL correta. O Apidog oferece três maneiras de configurar URLs para documentação online, dependendo das suas necessidades.
1. Usar URLs Base
Esta é a abordagem recomendada. Defina apenas o caminho no endpoint, como /pet/{petId}, e configure o endereço de serviço completo (por exemplo, https://product.example.com) na seção "Gerenciamento de Ambiente" como uma URL Base.
Ao publicar a documentação da API, selecione o ambiente de execução apropriado. O Apidog concatenará automaticamente a URL Base com o caminho do endpoint. Você também pode definir vários ambientes de execução, cada um com sua própria URL Base.
Na documentação online, os usuários podem alternar rapidamente os ambientes a partir de uma lista suspensa, e todas as URLs dos endpoints serão atualizadas de acordo. Isso torna conveniente validar APIs em diferentes ambientes.
Nota: Esteja atento a problemas de protocolo. Muitos navegadores restringem páginas HTTPS de chamar APIs HTTP. Se sua API usa HTTP, os usuários podem encontrar problemas de protocolo cruzado ao depurar em uma página de documentação HTTPS.
2. Incluir URLs Completas nos Endpoints
Outra opção é especificar a URL completa diretamente no endpoint, como https://product.example.com/pet/{petId}.
Isso garante que a URL de solicitação completa esteja visível, independentemente do ambiente de execução selecionado. No entanto, gerenciar alterações nos endereços do servidor torna-se complicado, pois você precisará atualizar cada endpoint individualmente. Por isso, este método é menos recomendado.
3. Usar Variáveis em URLs
Se você deseja que os usuários personalizem a URL para depuração, pode usar variáveis. Por exemplo, crie uma variável de ambiente BaseURL na seção "Gerenciamento de Ambiente" e referencie-a na URL Base como {{BaseURL}}.
Na documentação online, os usuários podem clicar no nome da variável e modificá-la para a URL desejada.
Alternativamente, você pode definir variáveis diretamente no endpoint, como {{BaseURL}}/pet/{petId}.
Para esse endpoint específico na documentação online, os usuários podem definir o valor da variável para enviar a solicitação.
Antes de publicar a documentação, certifique-se de que os "valores iniciais" no ambiente não contenham informações sensíveis (por exemplo, credenciais de autenticação), pois esses valores serão incluídos na documentação publicada e podem representar riscos de privacidade.
Configuração Adequada de Autenticação
Configuração de Autenticação Básica
Solicitações de endpoint bem-sucedidas geralmente exigem autenticação. O Apidog suporta vários tipos de autenticação, incluindo Bearer Token, API Key, OAuth2.0 e Basic Auth.
Você pode configurar a autenticação no nível do endpoint ou da pasta usando um esquema de segurança ou configurando-o manualmente.
Por exemplo, ao usar Bearer Token como tipo de autenticação, um campo "Token" aparece na parte superior do painel de depuração na documentação online. Os usuários podem inserir o valor do token diretamente sem adicionar manualmente o prefixo "Bearer". O Apidog lida com isso automaticamente, tornando-o mais conveniente do que adicionar um cabeçalho de autorização manualmente.
A vantagem dessa configuração é que as informações de autenticação podem ser compartilhadas entre múltiplos endpoints. Se vários endpoints usam o mesmo esquema ou tipo de segurança, você só precisa inserir as credenciais uma vez. Quaisquer atualizações nas credenciais serão aplicadas automaticamente a todos os endpoints associados.
As credenciais de autenticação são criptografadas e armazenadas localmente no navegador do usuário, gerenciadas por sessão e compartilhadas entre abas e janelas. Elas são limpas quando o navegador é fechado, reduzindo o risco de exposição de informações sensíveis na documentação publicada.
Configuração OAuth2.0
Para autenticação OAuth2.0, se você deseja que os usuários gerem tokens diretamente durante a depuração, configure os detalhes do servidor de autorização (por exemplo, URL de Autenticação, URL de Token) no projeto.
Ao usar o esquema de segurança OAuth2.0, os usuários precisarão inserir o ID do cliente, o segredo do cliente, etc., durante a depuração. Um pop-up os guiará pelo processo de autorização, e o access_token obtido será aplicado automaticamente às solicitações de API subsequentes.
Projetar Estruturas de Parâmetros Claras
Exibição de Parâmetros no Painel de Depuração
O painel de depuração exibe inteligentemente as seções de parâmetros com base no design do seu endpoint. Por exemplo, se o endpoint define apenas parâmetros de Caminho (Path), o painel de depuração mostrará apenas a seção Path, evitando seções de Query ou Body desnecessárias.
Essa clareza ajuda os usuários a entender quais parâmetros preencher sem serem distraídos por seções irrelevantes.
Fornecer Exemplo
Ao projetar endpoints, defina o tipo de cada parâmetro e os atributos necessários com precisão. Inclua descrições e exemplos claros, pois estes serão pré-preenchidos no painel de depuração, melhorando a usabilidade.
Evitar Cabeçalhos Redundantes
Se o endpoint define parâmetros de Body, não há necessidade de adicionar manualmente cabeçalhos como Content-Type: application/json. O Apidog lida automaticamente com esses cabeçalhos durante as solicitações.
Da mesma forma, se a autenticação estiver configurada, evite duplicá-la nos cabeçalhos. As configurações de autenticação têm precedência e substituirão quaisquer configurações de cabeçalho conflitantes.
Oferecer Exemplos de Solicitação Abrangentes
Para endpoints com corpos de solicitação JSON complexos, forneça múltiplos exemplos de corpo de solicitação durante o design.
Os usuários podem selecionar esses exemplos em um menu suspenso no painel de depuração, economizando tempo e reduzindo erros.
Certifique-se de que os dados de exemplo se assemelham de perto a cenários do mundo real, mas evite incluir informações sensíveis. Os usuários podem modificar esses exemplos conforme necessário.
Configurar Exemplos de Resposta Claros
Após enviar uma solicitação, o painel de depuração exibe a resposta completa, incluindo códigos de status, cabeçalhos e corpo. Como criador da documentação, configure exemplos de resposta claros para ajudar os usuários a entender os possíveis resultados.
Forneça múltiplos exemplos de resposta para cada endpoint, como sucesso (200), solicitação inválida (400) e não autorizado (401).
Preste atenção especial às respostas de erro, explicando claramente os códigos de erro e os formatos das mensagens para diferentes cenários. Isso ajuda os usuários a identificar e resolver problemas rapidamente durante a depuração.
Fornecer Código de Exemplo para Integração
Embora o Apidog gere automaticamente código de exemplo para linguagens de programação comuns, o código gerado pode não se alinhar totalmente às suas necessidades de negócio. Nesses casos, personalize os exemplos.
Você pode configurar quais linguagens exigem exemplos gerados automaticamente em "Configurações do Projeto -> Configurações de Recursos do Endpoint -> Exemplos de Código de Solicitação".
Além disso, você pode escrever código de exemplo personalizado para endpoints específicos na seção "Descrição do Endpoint".
Isso garante que os usuários vejam tanto exemplos gerados automaticamente quanto personalizados na documentação online, facilitando a integração.
Resumo
A experiência de depuração da documentação online depende muito da configuração adequada. Ao configurar URLs, autenticação, estruturas de parâmetros e exemplos de forma cuidadosa, você pode garantir que os usuários comecem a usar sua API rapidamente, sem se prenderem a detalhes técnicos.