Por padrão, suas documentações ficam acessíveis em um domínio [subdomain].apidog.io. No entanto, você pode personalizar isso configurando um domínio personalizado, o que significa que seu público poderá acessar sua documentação em um domínio adequado à sua organização.Domínios personalizados podem ser configurados por usuários com permissões de administrador. Siga estas etapas para configurar um domínio personalizado.Iniciando a configuração do domínio personalizado#
Você pode acessar as opções para configurar um domínio personalizado para um projeto no módulo Compartilhar do projeto. Basta clicar no menu Compartilhar Docs na barra lateral e, em seguida, navegar até a página de configurações Publicar no menu secundário.Você verá uma seção chamada Domínio Personalizado. Clique no botão Editar para iniciar a configuração do domínio personalizado.Há dois tipos de opções para configurar um domínio personalizado:1.
CNAME: Esta é a opção recomendada. É a mais fácil de configurar e manter. Também é a opção mais flexível, pois permite configurar um domínio personalizado para um subdomínio ou um domínio raiz.
2.
Reverse Proxy: Esta opção é mais avançada e exige que você use uma Content Delivery Network (CDN) ou configure um proxy reverso em seu próprio servidor. Ela é recomendada para usuários familiarizados com essas tecnologias.
Configurando CNAME#
Isto se aplica somente se você tiver selecionado a opção CNAME na etapa anterior.
1.
Configurar um registro CNAME
2.
Aguardar as alterações entrarem em vigor
Configurar um registro CNAME#
Os nomes dos campos e o que inserir de fato para configurar o registro podem variar entre painéis de controle de DNS, mas abordamos aqui as opções mais comuns. Se você não tiver certeza, 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 domínio apex (por exemplo, docs). Se você não tiver certeza de qual usar, consulte seu provedor de DNS.
O destino, valor ou destinação é para onde o subdomínio deve apontar. Você deverá ver o valor para isso nas configurações de Publicação no Apidog ao escolher a opção DNS CNAME. Ele será semelhante a {projectId}.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.
Você está usando Cloudflare?#
Se você estiver configurando 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 ocorre por dois motivos:Essa opção ofusca o destino DNS do seu domínio para o público, impedindo que o Apidog execute corretamente verificações de rotina no seu domínio personalizado.
Seu domínio personalizado já se beneficiará da CDN.
Aguardar as alterações entrarem em vigor#
A resposta curta: talvez você precise aguardar 10 minutes ~ 48 hours para que as alterações de DNS entrem em vigor antes de avançar para a próxima etapa.Lembra do campo TTL (Time To Live) que mencionamos anteriormente? Registros DNS ficam em cache por um período de tempo — o que geralmente é muito bom por motivos de desempenho, porque eles normalmente não mudam com muita frequência. Quando eles mudam, há um período de tempo (o valor TTL) durante o qual os servidores de cache DNS precisam que seu cache expire antes de verificar alterações e se comportar de acordo.Na maioria dos casos, é melhor aguardar pelo menos 10 minutos antes de avançar para a próxima e última etapa. Às vezes, tudo pode ser atualizado um pouco mais rapidamente, ou pode demorar mais. É raro isso levar 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 Pesquisar. Servidores de cache DNS ao redor do mundo responderão para informar qual é o resultado armazenado em cache. Você deverá verificar periodicamente esses resultados até que a grande maioria responda com o valor CNAME atribuído.Configurando CDN ou seu próprio servidor de proxy reverso#
Isto se aplica somente se você tiver selecionado a opção Reverse Proxy na etapa anterior.
Configurar AWS CloudFront como proxy reverso#
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. Aqui estão os valores que você precisará alterar.
| Configurações | Valor |
|---|
| Origin Domain Name | Defina como {projectId}.apidog.io |
| Name | Uma descrição para a origem. Este valor permite distinguir entre várias origens na mesma distribuição e, portanto, deve ser exclusivo. |
| 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 Publicação 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)
| Header Name | Valor |
|---|
| X-Apidog-Project-ID | Defina como {projectId} |
Você pode encontrar o valor projectId nas configurações do projeto Apidog.
4.
Configure as Default Cache Behavior Settings. Aqui estã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 AWS Web Application Firewall (WAF).
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, Distribution domain name (por exemplo, fd1fbc7cac6197.cloudfront.net).
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.
:8080 {
handle_path /* {
reverse_proxy http://{projectId.apidog.io {
header_up X-Apidog-Project-ID {projectId}
header_up Host "docs.example.com"
}
}
}
}
Você pode encontrar o valor {projectId} nas configurações do projeto Apidog.
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 do 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 pelo Apidog.Etapas de configuração:#
1.
Na página de configuração Custom Domain do 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 do Apidog).
proxy_set_header: Define cabeçalhos de requisição enviados pelo servidor proxy para o servidor upstream, garantindo que a requisição seja tratada corretamente.
/api-docs/ é o subdiretório do domínio personalizado e deve terminar com uma / na configuração do Nginx.
http://{projectId}.apidog.io/ também deve terminar com uma /.
Substitua {projectId} pelo ID do seu projeto 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.
Habilitar HTTPS#
A documentação online do 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 de mecanismos de busca do que sites HTTP.
Etapas para habilitar HTTPS:#
1.
Acesse 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 impedir que a comunicação seja sequestrada ou sofra ataques man-in-the-middle.
Gerenciamento de certificado SSL#
Depois que HTTPS estiver habilitado, você poderá escolher como gerenciar seu certificado SSL:Gerado pelo Apidog: O Apidog gerará automaticamente um certificado SSL.
Usar seu próprio certificado: Você pode carregar um certificado SSL e uma chave privada emitidos por uma autoridade certificadora (por exemplo, Let's Encrypt). Solução de problemas#
Se você estiver enfrentando problemas ao configurar seu domínio personalizado, entre em contato conosco via Discord.Você está usando Apidog Europe?#
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 do Apidog Europe na configuração anterior é {projectId}.eu.apidog.com. 
