Por predefinição, a sua documentação está acessível num domínio [subdomain].apidog.io. No entanto, pode personalizar isto ao definir um domínio personalizado, o que significa que o seu público poderá aceder à sua documentação num domínio adequado à sua organização.Os domínios personalizados podem ser definidos por utilizadores com permissões de administrador. Siga estes passos para definir um domínio personalizado.Iniciar a configuração do domínio personalizado#
Pode aceder às opções para definir um domínio personalizado para um projeto no módulo Share do projeto. Basta clicar no menu Share Docs na barra lateral e, em seguida, navegar para a página de definições Publish no menu secundário.Verá uma secção intitulada Custom Domain. Clique no botão Edit para iniciar a configuração do domínio personalizado.Existem dois tipos de opções para definir 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 definir um domínio personalizado para um subdomínio ou um domínio raiz.
2.
Reverse Proxy: Esta opção é mais avançada e requer que utilize uma Content Delivery Network (CDN) ou configure um proxy inverso no seu próprio servidor. É recomendada para utilizadores familiarizados com estas tecnologias.
Configurar CNAME#
Isto só é aplicável se tiver selecionado a opção CNAME no passo anterior.
1.
Configure um registo CNAME
2.
Aguarde que as alterações entrem em vigor
Configurar um registo CNAME#
Os nomes dos campos e o que deve introduzir para configurar o registo podem variar entre painéis de controlo de DNS, mas cobrimos aqui as opções mais comuns. Se tiver dúvidas, confirme com o seu fornecedor de DNS.O type é o tipo de registo DNS que pretende criar. Aqui, deve escolher CNAME.
O name ou DNS entry é onde introduz o seu subdomínio. Pode ser necessário introduzi-lo por completo (por exemplo, docs.example.com) ou talvez só precise de introduzir a parte antes do seu domínio de topo (por exemplo, docs). Se não tiver a certeza de qual usar, consulte o seu fornecedor de DNS.
O target, value ou destination é para onde o subdomínio deve apontar. Deve ver o valor correspondente nas definições Publish no Apidog quando escolher a opção DNS CNAME. Será algo como {projectId}.apidog.io. Deve introduzir este valor por completo (por exemplo, 12345678.apidog.io).
Também poderá ver um campo chamado TTL, que significa Time To Live. É o número de segundos durante os quais o registo DNS pode ser armazenado em cache. Se não tiver a certeza do que definir, sugerimos que selecione Auto ou mantenha o valor predefinido.
Está a utilizar Cloudflare?#
Se estiver a configurar DNS no painel de controlo da Cloudflare, certifique-se de que o proxy da Cloudflare (a nuvem laranja, também chamada "Proxy status" nas definições do seu domínio) está desativado. Isto deve-se a duas razões:Esta opção ofusca publicamente o destino DNS do seu domínio, impedindo o Apidog de executar corretamente verificações de rotina no seu domínio personalizado.
O seu domínio personalizado já beneficiará de CDN.
Aguarde que as alterações entrem em vigor#
A resposta curta: poderá ter de aguardar 10 minutes ~ 48 hours para que as alterações de DNS entrem em vigor antes de avançar para o passo seguinte.Lembra-se do campo TTL (Time To Live) que mencionámos anteriormente? Os registos DNS são armazenados em cache durante um determinado período — o que geralmente é muito positivo por motivos de desempenho, porque normalmente não mudam com muita frequência. Quando mudam, existe um período de tempo (o valor TTL) durante o qual os servidores de cache DNS precisam que a sua cache expire antes de verificarem alterações e se comportarem em conformidade.Na maioria dos casos, é melhor aguardar pelo menos 10 minutos antes de avançar para o próximo e último passo. Por vezes, tudo pode ser atualizado um pouco mais rapidamente ou pode demorar mais. É raro que isto demore mais de 48 horas.Quer verificar como está a decorrer este processo, conhecido como propagação? Pode utilizar uma ferramenta de pesquisa DNS, como WhatsMyDNS. Introduza o seu subdomínio completo, selecione CNAME na lista pendente e prima o botão Search. Os servidores de cache DNS em todo o mundo responderão para indicar qual é o resultado que têm em cache. Deve verificar periodicamente estes resultados até que a grande maioria responda com o valor CNAME que lhe foi atribuído.Configurar CDN ou o seu próprio servidor de proxy inverso#
Isto só é aplicável se tiver selecionado a opção Reverse Proxy no passo anterior.
Configurar AWS CloudFront como proxy inverso#
Pode utilizar o serviço CDN fornecido por fornecedores de cloud como AWS CloudFront ou Cloudflare Enterprise para o configurar como o seu próprio servidor de proxy inverso.No exemplo seguinte, vamos configurar AWS CloudFront como Reverse Proxy.1.
Inicie sessão na AWS e navegue para CloudFront. Clique em Create Distribution. 2.
Configure as definições da sua distribuição. Estes são os valores que terá de alterar.
| Definiçõ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, por isso, deve ser único. |
| Origin Protocol Policy | Defina como apenas HTTP |
| Alternate Domain Names (CNAMEs) | Defina como o seu nome de domínio personalizado (o mesmo que configurou nas definições 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 só aparecem depois de ter fornecido um Origin Domain Name)
| Nome do cabeçalho | Valor |
|---|
| X-Apidog-Project-ID | Defina como {projectId} |
Pode encontrar o valor projectId nas definições do projeto Apidog.
4.
Configure as Default Cache Behavior Settings. Estes são os valores que terá de alterar.
| Definiçã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 ative o AWS Web Application Firewall (WAF).
6.
Clique em Create distribution no fim da página. Verá a sua distribuição recém-criada na lista CloudFront Distributions. Tenha em atenção que o Status indicará In progress até que a distribuição esteja Deployed.
7.
Adicione um novo registo CNAME ao seu DNS para o seu domínio personalizado, apontando para o CloudFront Domain Name da sua Distribution. Pode encontrá-lo clicando no seu Distribution ID, no separador General, em Distribution domain name (por exemplo, fd1fbc7cac6197.cloudfront.net).
Configurar o seu próprio servidor de proxy inverso#
Pode configurar o seu próprio servidor de proxy inverso para a sua documentação da API. No exemplo seguinte, utilizaremos Nginx como servidor de proxy inverso.1.
Adicione o seguinte conteúdo ao ficheiro 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"
}
}
}
}
Pode encontrar o valor {projectId} nas definições do projeto Apidog.
2.
Configure o registo DNS do seu nome de domínio personalizado para apontar para o seu servidor de proxy inverso.
Implementar documentos de API num subdiretório de um domínio personalizado#
O Reverse Proxy do Apidog permite que documentos de API sejam implementados num subdiretório de um domínio personalizado. Por exemplo, pode implementar a documentação no caminho /api-docs num domínio como https://example.com. Quando os utilizadores visitarem https://example.com/api-docs, estarão a aceder à documentação de API online alojada pelo Apidog.Passos de configuração:#
1.
Na página de definição Custom Domain do Apidog, introduza o seu domínio personalizado.
2.
Selecione Reverse Proxy e ative Use Subdirectory; em seguida, introduza o caminho do subdiretório.
3.
Em seguida, terá de modificar o ficheiro de configuração do seu servidor web. Assumindo que está a utilizar Nginx para fazer proxy do seu serviço, pode consultar a seguinte configuração:
proxy_pass: Encaminha pedidos de cliente para outro servidor (como o servidor de documentação de API do Apidog).
proxy_set_header: Define cabeçalhos de pedido enviados pelo servidor proxy para o servidor upstream, garantindo que o pedido é tratado 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, precisa de reiniciar o Nginx no seu servidor.
Ativar HTTPS#
A documentação online do Apidog suporta o protocolo HTTPS, que tem várias vantagens em relação ao HTTP:Transmissão segura de dados: O HTTPS utiliza encriptação SSL/TLS para garantir a segurança da transmissão de dados, impedindo que terceiros intercetem informações.
Otimização SEO: Os rastreadores dos motores de pesquisa preferem utilizar HTTPS porque oferece melhor segurança e proteção da privacidade. Portanto, os sites HTTPS podem ter maior autoridade nas classificações dos motores de pesquisa do que os sites HTTP.
Passos para ativar HTTPS:#
1.
Aceda à página Publish e abra o separador Custom Domain.
2.
Ative HTTPS para ativar HTTPS e, opcionalmente, pode ativar Always Use HTTPS para impedir que a comunicação seja sequestrada ou para evitar ataques man-in-the-middle.
Gestão de certificados SSL#
Assim que o HTTPS estiver ativado, pode escolher como gerir o seu certificado SSL:Generated by Apidog: O Apidog gerará automaticamente um certificado SSL.
Use Your Own Certificate: Pode carregar um certificado SSL e uma chave privada emitidos por uma autoridade de certificação (por exemplo, Let's Encrypt). Resolução de problemas#
Se tiver problemas ao configurar o seu domínio personalizado, contacte-nos através do Discord.Está a utilizar o Apidog Europe?#
Se estiver a utilizar o Apidog Europe, certifique-se de que está a utilizar o domínio correto para a configuração do seu domínio personalizado.O domínio correto para o Apidog Europe na configuração anterior é {projectId}.eu.apidog.com. 
