A documentação profissional de API merece um domínio profissional. Por predefinição, a documentação do Apidog está acessível num domínio <subdomain>.apidog.io. No entanto, pode personalizá-lo configurando o seu próprio domínio, permitindo que o seu público aceda à documentação num domínio alinhado com a identidade da sua organização.
Para aceder às definições de domínio personalizado, navegue até ao menu Publish Docs na barra lateral e, em seguida, aceda à página de definições Publish. Encontrará uma secção Custom Domain, onde pode clicar no botão Edit para iniciar a configuração.
Existem 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 como para domínios raiz, oferecendo máxima flexibilidade.
2.
Proxy Inverso (Avançado): Requer a utilização de uma Rede de Distribuição de Conteúdos (CDN) ou a configuração de um proxy inverso no seu próprio servidor; recomendado para utilizadores familiarizados com estas tecnologias.
Os nomes dos campos e os passos de configuração podem diferir entre painéis de controlo de DNS, mas os conceitos principais permanecem os mesmos. Se tiver dúvidas, confirme com o seu fornecedor de DNS.
O tipo é o tipo de registo DNS que pretende criar. Aqui, deve escolher CNAME.
O nome ou entrada DNS é onde introduz o seu subdomínio. Poderá ter de o introduzir por completo (por exemplo, docs.example.com) ou poderá apenas ter de introduzir a parte antes do seu domínio apex (por exemplo, docs). Se não tiver a certeza de qual utilizar, verifique com o seu fornecedor de DNS.
O destino, valor ou destinação é para onde o subdomínio deve apontar. Deverá ver o valor correspondente nas definições Publish no Apidog quando escolher a opção DNS CNAME. Terá um aspeto semelhante a {docsSiteId}.apidog.io. Deve introduzir este valor por completo (por exemplo, 12345678.apidog.io).
Poderá também ver um campo chamado TTL, que significa Time To Live. É o número de segundos durante os quais o registo DNS pode ser colocado em cache. Se não tiver a certeza do que definir, sugerimos que selecione Auto ou mantenha o valor predefinido.
Segue-se um exemplo de como uma configuração correta aparece no painel de controlo da Cloudflare:
Um registo CNAME não pode coexistir com outro registo para o mesmo nome. Se já tiver um registo A, registo AAAA, registo TXT ou qualquer outro tipo de registo para o subdomínio escolhido, terá de os remover primeiro, antes de adicionar o registo CNAME.
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 dois motivos:
Esta opção oculta 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.
Novamente, desative o proxy da Cloudflare para garantir que a sua documentação é servida sem problemas.
Quanto Tempo Demoram as Alterações a Entrar em Vigor?#
A resposta curta: poderá ter de aguardar entre 10 minutos e 48 horas 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 colocados em cache durante um período de tempo — o que normalmente é muito bom por motivos de desempenho, porque geralmente 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 respetiva cache expire antes de verificarem quaisquer alterações e se comportarem em conformidade.Na maioria dos casos, é melhor aguardar pelo menos 10 minutos antes de avançar para o passo seguinte e final. 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 progredir este processo, conhecido como propagação? Pode utilizar uma ferramenta de consulta 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 em cache. Deve verificar periodicamente estes resultados até que a grande maioria responda com o valor CNAME atribuído.
Configurar CDN ou o Seu Próprio Servidor de Proxy Inverso#
Aplicabilidade
Esta secção só é aplicável se tiver selecionado a opção Reverse Proxy no passo anterior.
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, configuraremos o AWS CloudFront como Proxy Inverso.
1.
Inicie sessão na AWS e navegue até CloudFront. Clique em Create Distribution.
2.
Configure as definições da sua distribuição. Eis os valores que terá de alterar.
Definições
Valor
Origin Domain Name
Defina como {docsSiteId}.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 para o 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 apenas depois de ter fornecido um Origin Domain Name)
Nome do Cabeçalho
Valor
X-Apidog-Docs-Site-ID
Defina como {docsSiteId}
{docsSiteId} é o seu Docs Site ID, que pode ser encontrado no painel de domínio personalizado. Certifique-se de que introduz o ID correto.
4.
Configure as Default Cache Behavior Settings. Eis 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 fundo da página. Verá a distribuição recém-criada na sua lista CloudFront Distributions. Note 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. Isto pode ser encontrado clicando no seu Distribution ID, no separador General, em Distribution domain name (por exemplo, fd1fbc7cac6197.cloudfront.net).
Pode utilizar Cloudflare Workers para atuar como proxy inverso. Isto permite-lhe manter o seu domínio com proxy (Orange Cloud), garantindo ao mesmo tempo que o Apidog recebe os identificadores de projeto necessários.
Clique em Create Application e depois em Create Worker. (Continue com Start with Hello World!, se lhe for solicitado que selecione um método)
3.
Dê um nome ao seu worker (por exemplo, apidog-docs-proxy) e clique em Deploy.
4.
Clique em Edit Code e substitua o script existente pelo seguinte:
Pode encontrar o seu {docsSiteId} no painel de domínio personalizado. Certifique-se de que introduz o ID correto tanto na variável targetHost como na variável docsSiteId.
5.
Clique em Save and Deploy.
6.
Navegue até ao separador Settings do seu Worker, selecione Domains & Routes e clique no botão +Add.
7.
Introduza o seu domínio personalizado (por exemplo, docs.example.com). A Cloudflare tratará automaticamente dos registos DNS e dos certificados SSL.
8.
Certifique-se de que o SSL/TLS encryption mode da Cloudflare está definido como Full ou Full (Strict) para permitir comunicação segura entre a Cloudflare e o Apidog.
Pré-requisito
Antes de associar um domínio personalizado ao seu worker, certifique-se de que o domínio (por exemplo, example.com) já está adicionado à sua conta Cloudflare e que os respetivos nameservers estão ativos.
Configurar o Seu Próprio Servidor de Proxy Inverso#
Pode configurar o seu próprio servidor de proxy inverso para a documentação da sua 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.
{docsSiteId} é o seu Docs Site ID, que pode ser encontrado no painel de domínio personalizado. Certifique-se de que introduz o ID correto.
2.
Configure o registo DNS para o seu nome de domínio personalizado 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.
Na página de definições 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.
De 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 clientes 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://{docsSiteId}.apidog.io/ também deve terminar com uma /.
Substitua {docsSiteId} pelo ID do site de documentação do Apidog.
docs.example.com é um domínio personalizado de exemplo. Substitua-o pelo seu domínio personalizado real.
Após a configuração, tem de reiniciar o Nginx no seu servidor.
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 terceiros de intercetarem informações.
Otimização de SEO: Os rastreadores de motores de pesquisa preferem utilizar HTTPS porque oferece melhor segurança e proteção da privacidade. Por conseguinte, os websites HTTPS podem ter maior autoridade nas classificações dos motores de pesquisa do que os websites HTTP.
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 sujeita a ataques man-in-the-middle.
Depois de ativar HTTPS, pode escolher como gerir o seu certificado SSL:
Gerado pelo Apidog: O Apidog irá gerar automaticamente um certificado SSL.
Utilizar o Seu Próprio Certificado: Pode carregar um certificado SSL e uma chave privada emitidos por uma autoridade certificadora (por exemplo, Let's Encrypt).
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 é {docsSiteId}.eu.apidog.com.
