Depois de escrever a documentação da sua API e se preparar para publicá-la, surge uma pergunta crucial: Quem deve ter acesso para visualizá-la?
A documentação deve ser totalmente pública? Ou restrita à sua equipe interna? Talvez seus parceiros externos precisem de acesso – mas não qualquer um.
Criar uma versão separada da documentação para cada cenário seria demorado e ineficiente. Na realidade, as necessidades de acesso são frequentemente muito específicas – talvez apenas um departamento deva vê-la, ou talvez seus parceiros devam acessá-la apenas de dentro de sua rede corporativa.
Felizmente, o Apidog oferece múltiplas opções de controle de acesso para atender a todas essas necessidades. Ao publicar um site de documentação, basta selecionar o método de controle de acesso que se adequa ao seu caso de uso.
1. Público: Qualquer um pode visualizar
Se sua API estiver aberta para uso público – como a API aberta do seu produto – basta definir o controle de acesso como "Público". Qualquer pessoa com o link pode visualizar a documentação.
Dica profissional: O Apidog também possui um API Hub, uma plataforma estilo marketplace onde desenvolvedores podem navegar e descobrir APIs. Publique sua documentação lá para aumentar a visibilidade e a adoção.
2. Protegido por Senha: Barreira Simples
Às vezes você não quer que sua documentação seja totalmente pública, mas também quer evitar configurações complexas. A proteção por senha é uma solução direta – defina uma senha, e somente aqueles que a conhecem podem acessar a documentação.
A configuração é fácil:
- Escolha “Protegido por Senha”
- Defina uma senha manualmente ou deixe o sistema gerar uma
- Compartilhe com colegas de trabalho ou parceiros
Melhor para: Compartilhamento de curto prazo ou temporário, como permitir que um parceiro revise o design da sua API. Depois, basta atualizar a senha ou despublicar a documentação. Simples e limpo.
Mas tenha em mente: Senhas podem ser compartilhadas acidentalmente. Se você precisar de um controle mais rigoroso, considere outras opções.
3. Lista de Permissão de IP: Restringir Acesso a Redes Específicas
Se sua equipe ou parceiros estão baseados em locais de escritório fixos, a lista de permissão de IP pode ser sua melhor escolha.
Funciona assim:
- Apenas usuários dos endereços IP ou faixas especificados podem acessar a documentação
- IPs não autorizados são automaticamente negados
Pense nisso como um firewall para sua documentação.
Melhor para:
- Ambientes corporativos
- Limitar o acesso à sua rede interna
- Permitir acesso de parceiros apenas de sua rede de escritório
Você pode configurar um único IP ou uma faixa de IPs inteira.
Bônus: Você também pode habilitar a lista de permissão de IP para acesso a projetos de equipe nas Configurações de Equipe do Apidog (plano Enterprise necessário). Uma vez ativado, apenas usuários de IPs permitidos podem acessar seus projetos internos.
4. Lista de Permissão de E-mail: Acesso Baseado em Identidade
Preocupado que senhas possam vazar ou que IPs mudem frequentemente? A lista de permissão de e-mail é uma alternativa flexível e segura.
Basta adicionar os endereços de e-mail da sua equipe ou parceiros à lista de permissão. Os usuários podem então acessar a documentação via um código de verificação de e-mail de uso único.
Ele também suporta curingas – por exemplo, *@apidog.com permite que todos os usuários com o domínio da sua empresa acessem a documentação.
Benefícios:
- Fácil de gerenciar: adicione ou remova usuários conforme necessário
- Mais seguro que senhas: usuários não autorizados não podem visualizar a documentação mesmo se tiverem o link
- Ótimo para equipes distribuídas ou forças de trabalho móveis
5. Página de Login Personalizada: Integrar com Seu Próprio Sistema de Autenticação
Se nenhum dos métodos acima atende às suas necessidades, há uma opção mais avançada – Página de Login Personalizada. Isso permite que você conecte seu próprio sistema de autenticação para controlar o acesso.
Veja como funciona:
- Quando um usuário tenta acessar o site da documentação, ele é redirecionado para sua página de login.
- Após a autenticação, seu servidor gera um token JWT.
- O usuário é redirecionado de volta ao site da documentação com o token como parâmetro.
- O Apidog verifica o token e concede acesso se for válido.
Essa abordagem permite que você defina permissões exatamente como suas necessidades de negócio exigem. Embora exija algum desenvolvimento, é uma ótima opção para empresas com necessidades complexas de controle de acesso.
Consulte a Documentação de Ajuda para detalhes sobre como implementar uma página de login personalizada.
Como Escolher o Método de Controle de Acesso Correto
Com tantas opções, você pode se perguntar: Qual devo escolher?
Depende do seu caso de uso:
| Caso de Uso | Método Recomendado |
|---|---|
| APIs públicas, busca por exposição | Acesso Público |
| Trabalho em equipe ou compartilhamento externo de curto prazo | Proteção por Senha |
| Redes internas ou de parceiros seguras | Lista de Permissão de IP |
| Controlar acesso por identidade do usuário | Lista de Permissão de E-mail |
| Usar seu próprio sistema de login | Página de Login Personalizada |
Dica: Você pode combinar múltiplos métodos. Por exemplo:
- Use uma lista de permissão de IP para membros da equipe interna
- Use uma lista de permissão de e-mail para parceiros externos
- Use proteção por senha para demonstrações temporárias
Com o Apidog, você pode publicar múltiplos sites de documentação, cada um com seu próprio controle de acesso e um conjunto personalizado de endpoints de API. Isso significa que diferentes públicos veem apenas o que precisam – nada mais, nada menos.