Professional API documentation deserves a professional domain. By default, Apidog documentation is accessible on a [subdomain].apidog.io domain. However, you can customize this by setting up your own domain, allowing your audience to access documentation on a domain that aligns with your organization's branding.
To access custom domain settings, navigate to the Publish Docs menu in the sidebar, then go to the Publish settings page. You'll find a Custom Domain section where you can click the Edit button to begin setup.
There are two types of options for setting a custom domain:
1.
CNAME (Recommended): The easiest to set up and maintain. Works for both subdomains and root domains, providing maximum flexibility
2.
Reverse Proxy (Advanced): Requires using a Content Delivery Network (CDN) or setting up a reverse proxy on your own server. Recommended for users familiar with these technologies
The field names and configuration steps may differ between DNS control panels, but the core concepts remain the same. If you're uncertain, verify with your DNS provider.
The type is the kind of DNS record that you want to create. Here, you need to choose CNAME.
The name or DNS entry is where you enter your subdomain. You might need to enter it in full (e.g. docs.example.com) or you might just need to enter the part before your apex domain (e.g. docs). If you’re not sure which to use, check with your DNS provider.
The target or value or destination is where the subdomain should be pointed. You should see the value for this in the Publish settings in Apidog when you choose the DNS CNAME option. It will look something like {docsSiteId}.apidog.io. You should enter this value in full (e.g. 12345678.apidog.io).
You might also see a field named TTL, which stands for Time To Live. It’s the number of seconds that the DNS record can be cached for. If you’re not sure what to set, we suggest select Auto or remain default value.
Here’s an example of how a correct configuration looks in Cloudflare’s control panel:
Note: CNAME record cannot co-exist with another record for the same name. If you already have an A record, AAAA record, TXT record, or any other type of record for your chosen subdomain, you would need to remove those first, before adding the CNAME record.
Are you using Cloudflare?
If you are configuring DNS in Cloudflare’s control panel, please ensure that Cloudflare’s proxying (the orange cloud, also called "Proxy status" in your domain settings) is disabled. This is for two reasons:
This option obfuscates the DNS target for your domain to the public, preventing Apidog from properly running routine checks on your custom domain.
Your custom domain will already benefit from CDN.
Again, please turn off Cloudflare proxying to ensure that your documentation is served without issues.
The short answer: you might need to wait 10 minutes ~ 48 hours for the DNS changes to take effect before moving onto the next step.Remember the TTL (Time To Live) field we mentioned earlier? DNS records are cached for a period of time — which is usually a very good thing for performance reasons, because they typically don’t change very often. When they do change, there is a period of time (the TTL value) where DNS cache servers need their cache to expire before they will check for any changes and behave accordingly.In most cases, it’s best to allow at least 10 minutes before moving onto the next and final step. Sometimes it could all update a bit more quickly, or it could take longer. It’s rare for this to take longer than 48 hours.Want to check how this process, known as propagation, is progressing? You could use a DNS lookup tool, such as WhatsMyDNS. Enter your full subdomain, select CNAME from the dropdown list, and press the Search button. DNS cache servers around the world will respond to let you know what their cached result is. You’ll want to periodically check these results until the vast majority respond with your assigned CNAME value.
You can utilize the CDN service provided by cloud vendors like AWS CloudFront, Cloudflare Enterprise to set it up as your own reverse proxy server.In the following example, we will configure AWS CloudFront as Reverse Proxy.
1.
Log in to AWS, and navigate to CloudFront. Click Create Distribution.
2.
Configure your distribution settings. Here are the values you'll need to change.
Settings
Value
Origin Domain Name
Set to {docsSiteId}.apidog.io
Name
A description for the origin. This value lets you distinguish between multiple origins in the same distribution and therefore must be unique.
Origin Protocol Policy
Set to HTTP Only
Alternate Domain Names (CNAMEs)
Set to your custom domain name (the same one your configured in the Publish settings during the custom domain setup)
SSL Certificate
Set to the SSL Certificate for your custom domain stored in AWS Certificate Manager (ACM).
3.
Provide information on the Origin Custom Headers (the Header Name and Value fields appear only after you've provided an Origin Domain Name)
Header Name
Value
X-Apidog-Docs-Site-ID
Set to {docsSiteId}
{docsSiteId} is your Docs Site ID, which can be found in the custom domain panel. Please make sure to enter the correct ID.
4.
Configure the Default Cache Behavior Settings. Here are the values you'll need to change.
Setting
Value
Viewer Protocol Policy
Select Redirect HTTP to HTTPS
Allowed HTTP Methods
Select GET, HEAD, OPTIONS, PUT, POST, PATCH, DELETE.
Cache and origin request settings
Select Use legacy cache settings. Select All for Headers, Query strings and Cookies
5.
Do not enable AWS Web Application Firewall (WAF).
6.
Click Create distribution at bottom of the page. You'll see your newly-created distribution in your CloudFront Distributions list. Note that the Status will reflect In progress until the distribution is Deployed.
7.
Add a new CNAME record to your DNS for your custom domain pointing to the CloudFront Domain Name for your Distribution. This can be found by clicking on your Distribution ID, under the General tab, Distribution domain name (for example, fd1fbc7cac6197.cloudfront.net).
{docsSiteId} is your Docs Site ID, which can be found in the custom domain panel. Please make sure to enter the correct ID.
2.
Configure DNS record for your custom domain name to point to your reverse proxy server.
Deploying API Documents to a Subdirectory of a Custom Domain#
Apidog's Reverse Proxyallows API documents to be deployed to a subdirectory of a custom domain. For instance, you can deploy the documentation to the /api-docs path on a domain like https://example.com. When users visit https://example.com/api-docs, they will be accessing the online API documentation hosted by Apidog.
On Apidog's Custom Domain setting page, enter your custom domain.
2.
Select Reverse Proxy and enable Use Subdirectory, then enter the subdirectory path.
3.
Next, you'll need to modify the configuration file of your web server. Assuming you're using Nginx to proxy your service, you can refer to the following configuration:
proxy_pass: Forward client requests to another server (such as Apidog’s API documentation server).
proxy_set_header: Set request headers sent by the proxy server to the upstream server, ensuring the request is properly handled.
/api-docs/ is the subdirectory of the custom domain, and it must end with a / in the Nginx configuration.
http://{docsSiteId}.apidog.io/ must also end with a /.
Replace {docsSiteId} with your Apidog doc site ID.
docs.example.com is a sample custom domain. Replace it with your actual custom domain.
After configuration, you need to restart Nginx on your server.
Apidog's online documentation supports the HTTPS protocol, which has several advantages over HTTP:
Secure data transmission: HTTPS uses SSL/TLS encryption to ensure the security of data transmission, preventing third parties from intercepting information.
SEO optimization: Search engine crawlers prefer to use HTTPS because it offers better security and privacy protection. Therefore, HTTPS websites may have higher authority in search engine rankings than HTTP websites.
Go to the Publish page and open the Custom Domain tab.
2.
Switch on HTTPS to enable HTTPS, and optionally, you can enable Always Use HTTPS to prevent communication from being hijacked or man-in-the-middle attacks.
If you are using Apidog Europe, please ensure that you are using the correct domain for your custom domain setup.The correct domain for Apidog Europe in previous setup is {docsSiteId}.eu.apidog.com.
