Uma documentação de API profissional merece um domínio profissional. Por padrão, a documentação da Apidog é acessível em um domínio <subdomain>.apidog.io. No entanto, você pode personalizar isso configurando seu próprio domínio, permitindo que seu público acesse a documentação em um domínio alinhado à identidade da sua organização.
Antes de configurar um domínio personalizado, certifique-se de que você tenha:
Permissões de administrador para o projeto da Apidog
Propriedade ou controle do domínio que deseja usar
Acesso às configurações de DNS do seu domínio
(Para o método de Proxy Reverso) Familiaridade com configuração de CDN ou proxy reverso
Iniciando a Configuração de Domínio Personalizado#
Para acessar as configurações de domínio personalizado, navegue até o menu Publish Docs na barra lateral e, em seguida, vá para a página de configurações Publish. Você encontrará uma seção Custom Domain, onde poderá clicar no botão Edit para iniciar a configuração.
Há dois tipos de opções para definir um domínio personalizado:
1.
CNAME (Recomendado): O mais fácil de configurar e manter; funciona tanto para subdomínios quanto para domínios raiz, oferecendo máxima flexibilidade.
2.
Proxy Reverso (Avançado): Requer o uso de uma Content Delivery Network (CDN) ou a configuração de um proxy reverso no seu próprio servidor; recomendado para usuários familiarizados com essas tecnologias.
Os nomes dos campos e as etapas de configuração podem variar entre painéis de controle de DNS, mas os conceitos principais permanecem os mesmos. Se você tiver dúvidas, verifique com seu provedor de DNS.
O tipo é o tipo de registro DNS que você deseja criar. Aqui, você precisa escolher CNAME.
O nome ou entrada DNS é onde você insere seu subdomínio. Talvez seja necessário inseri-lo por completo (por exemplo, docs.example.com) ou talvez você precise inserir apenas a parte antes do seu domínio apex (por exemplo, docs). Se você não tiver certeza de qual usar, consulte seu provedor de DNS.
O destino, valor ou destination é para onde o subdomínio deve apontar. Você deve ver esse valor nas configurações de Publish na Apidog ao escolher a opção DNS CNAME. Ele será parecido com {docsSiteId}.apidog.io. Você deve inserir esse valor por completo (por exemplo, 12345678.apidog.io).
Você também pode ver um campo chamado TTL, que significa Time To Live. É o número de segundos durante os quais o registro DNS pode ficar em cache. Se você não tiver certeza do que definir, sugerimos selecionar Auto ou manter o valor padrão.
Veja um exemplo de como uma configuração correta aparece no painel de controle da Cloudflare:
O registro CNAME não pode coexistir com outro registro para o mesmo nome. Se você já tiver um registro A, registro AAAA, registro TXT ou qualquer outro tipo de registro para o subdomínio escolhido, será necessário removê-los primeiro, antes de adicionar o registro CNAME.
Você está usando Cloudflare?
Se você estiver configurando o DNS no painel de controle da Cloudflare, certifique-se de que o proxy da Cloudflare (a nuvem laranja, também chamada de "Proxy status" nas configurações do seu domínio) esteja desativado. Isso se deve a dois motivos:
Essa opção ofusca o destino DNS do seu domínio para o público, impedindo que a Apidog execute adequadamente verificações de rotina no seu domínio personalizado.
Seu domínio personalizado já se beneficiará de CDN.
Novamente, desative o proxy da Cloudflare para garantir que sua documentação seja servida sem problemas.
Quanto Tempo Leva para as Alterações Entrarem em Vigor?#
A resposta curta: talvez você precise aguardar de 10 minutos a 48 horas para que as alterações de DNS entrem em vigor antes de passar para a próxima etapa.Lembra do campo TTL (Time To Live) que mencionamos anteriormente? Os registros DNS são armazenados em cache por um período — o que geralmente é muito bom por motivos de desempenho, pois normalmente eles não mudam com frequência. Quando eles mudam, há um período de tempo (o valor TTL) em que os servidores de cache DNS precisam que seu cache expire antes de verificarem alterações e agirem de acordo.Na maioria dos casos, é melhor aguardar pelo menos 10 minutos antes de passar para a próxima e última etapa. Às vezes, tudo pode ser atualizado um pouco mais rapidamente, ou pode levar mais tempo. É raro que isso demore mais de 48 horas.Quer verificar como esse processo, conhecido como propagação, está avançando? Você pode usar uma ferramenta de consulta DNS, como WhatsMyDNS. Insira seu subdomínio completo, selecione CNAME na lista suspensa e pressione o botão Search. Servidores de cache DNS ao redor do mundo responderão informando qual é o resultado armazenado em cache. Você deve verificar esses resultados periodicamente até que a grande maioria responda com o valor CNAME atribuído a você.
Configurando CDN ou Seu Próprio Servidor de Proxy Reverso#
Aplicabilidade
Esta seção é aplicável somente se você selecionou a opção Reverse Proxy na etapa anterior.
Você pode utilizar o serviço de CDN fornecido por fornecedores de nuvem como AWS CloudFront e Cloudflare Enterprise para configurá-lo como seu próprio servidor de proxy reverso.No exemplo a seguir, configuraremos o AWS CloudFront como Proxy Reverso.
1.
Faça login na AWS e navegue até CloudFront. Clique em Create Distribution.
2.
Configure as definições da sua distribuição. Estes são os valores que você precisará alterar.
Configurações
Valor
Origin Domain Name
Defina como {docsSiteId}.apidog.io
Name
Uma descrição para a origem. Esse valor permite distinguir entre várias origens na mesma distribuição e, portanto, deve ser único.
Origin Protocol Policy
Defina como somente HTTP
Alternate Domain Names (CNAMEs)
Defina como seu nome de domínio personalizado (o mesmo que você configurou nas configurações de Publish durante a configuração do domínio personalizado)
SSL Certificate
Defina como o Certificado SSL do seu domínio personalizado armazenado no AWS Certificate Manager (ACM).
3.
Forneça informações nos Origin Custom Headers (os campos Header Name e Value aparecem somente depois que você fornece um Origin Domain Name)
Nome do Cabeçalho
Valor
X-Apidog-Docs-Site-ID
Defina como {docsSiteId}
{docsSiteId} é o ID do seu site de Docs, que pode ser encontrado no painel de domínio personalizado. Certifique-se de inserir o ID correto.
4.
Configure as Default Cache Behavior Settings. Estes são os valores que você precisará alterar.
Configuração
Valor
Viewer Protocol Policy
Selecione Redirect HTTP to HTTPS
Allowed HTTP Methods
Selecione GET, HEAD, OPTIONS, PUT, POST, PATCH, DELETE.
Cache and origin request settings
Selecione Use legacy cache settings. Selecione All para Headers, Query strings e Cookies
5.
Não habilite o Web Application Firewall (WAF) da AWS.
6.
Clique em Create distribution na parte inferior da página. Você verá sua distribuição recém-criada na lista CloudFront Distributions. Observe que o Status exibirá In progress até que a distribuição esteja Deployed.
7.
Adicione um novo registro CNAME ao seu DNS para seu domínio personalizado apontando para o CloudFront Domain Name da sua Distribution. Isso pode ser encontrado clicando no seu Distribution ID, na guia General, em Distribution domain name (por exemplo, fd1fbc7cac6197.cloudfront.net).
Você pode usar Cloudflare Workers para atuar como um proxy reverso. Isso permite manter seu domínio com proxy (Nuvem Laranja), garantindo ao mesmo tempo que a Apidog receba os identificadores de projeto necessários.
Clique em Create Application e depois em Create Worker. (Continue com Start with Hello World!, se for solicitado que você selecione um método)
3.
Nomeie seu worker (por exemplo, apidog-docs-proxy) e clique em Deploy.
4.
Clique em Edit Code e substitua o script existente pelo seguinte:
Você pode encontrar seu {docsSiteId} no painel de domínio personalizado. Certifique-se de inserir o ID correto nas variáveis targetHost e docsSiteId.
5.
Clique em Save and Deploy.
6.
Navegue até a guia Settings do seu Worker, selecione Domains & Routes e clique no botão +Add.
7.
Insira seu domínio personalizado (por exemplo, docs.example.com). A Cloudflare cuidará automaticamente dos registros DNS e certificados SSL.
8.
Certifique-se de que o SSL/TLS encryption mode da Cloudflare esteja definido como Full ou Full (Strict) para permitir comunicação segura entre a Cloudflare e a Apidog.
Pré-requisito
Antes de anexar um domínio personalizado ao seu worker, certifique-se de que o domínio (por exemplo, example.com) já esteja adicionado à sua conta da Cloudflare e que seus nameservers estejam ativos.
Configurando Seu Próprio Servidor de Proxy Reverso#
Você pode configurar seu próprio servidor de proxy reverso para sua documentação de API. No exemplo a seguir, usaremos Nginx como servidor de proxy reverso.
1.
Adicione o conteúdo a seguir ao arquivo de configuração do Nginx para uma configuração simples.
{docsSiteId} é o ID do seu site de Docs, que pode ser encontrado no painel de domínio personalizado. Certifique-se de inserir o ID correto.
2.
Configure o registro DNS do seu nome de domínio personalizado para apontar para seu servidor de proxy reverso.
Implantando Documentos de API em um Subdiretório de um Domínio Personalizado#
O Reverse Proxy da Apidog permite que documentos de API sejam implantados em um subdiretório de um domínio personalizado. Por exemplo, você pode implantar a documentação no caminho /api-docs em um domínio como https://example.com. Quando os usuários visitarem https://example.com/api-docs, eles acessarão a documentação de API online hospedada pela Apidog.
Na página de configuração Custom Domain da Apidog, insira seu domínio personalizado.
2.
Selecione Reverse Proxy e habilite Use Subdirectory; em seguida, insira o caminho do subdiretório.
3.
Em seguida, você precisará modificar o arquivo de configuração do seu servidor web. Supondo que você esteja usando Nginx para fazer proxy do seu serviço, você pode consultar a seguinte configuração:
proxy_pass: Encaminha requisições de clientes para outro servidor (como o servidor de documentação de API da Apidog).
proxy_set_header: Define cabeçalhos de requisição enviados pelo servidor proxy ao servidor upstream, garantindo que a requisição seja processada corretamente.
/api-docs/ é o subdiretório do domínio personalizado e deve terminar com uma / na configuração do Nginx.
http://{docsSiteId}.apidog.io/ também deve terminar com uma /.
Substitua {docsSiteId} pelo ID do site de documentação da Apidog.
docs.example.com é um domínio personalizado de exemplo. Substitua-o pelo seu domínio personalizado real.
Após a configuração, você precisa reiniciar o Nginx no seu servidor.
A documentação online da Apidog é compatível com o protocolo HTTPS, que tem várias vantagens em relação ao HTTP:
Transmissão segura de dados: HTTPS usa criptografia SSL/TLS para garantir a segurança da transmissão de dados, impedindo que terceiros interceptem informações.
Otimização de SEO: Rastreadores de mecanismos de busca preferem usar HTTPS porque ele oferece melhor segurança e proteção de privacidade. Portanto, sites HTTPS podem ter maior autoridade nos rankings dos mecanismos de busca do que sites HTTP.
Vá para a página Publish e abra a guia Custom Domain.
2.
Ative HTTPS para habilitar HTTPS e, opcionalmente, você pode habilitar Always Use HTTPS para evitar que a comunicação seja sequestrada ou sofra ataques man-in-the-middle.
Depois que o HTTPS estiver habilitado, você poderá escolher como gerenciar seu certificado SSL:
Gerado pela Apidog: A Apidog gerará automaticamente um certificado SSL.
Usar Seu Próprio Certificado: Você pode fazer upload de um certificado SSL e de uma chave privada emitidos por uma autoridade certificadora (por exemplo, Let's Encrypt).
Se você estiver usando Apidog Europe, certifique-se de estar usando o domínio correto para a configuração do seu domínio personalizado.O domínio correto para Apidog Europe na configuração anterior é {docsSiteId}.eu.apidog.com.
