Ultimate Guide: Hosting API Documentation on a Custom Domain

In the competitive world of software development, delivering clear and accessible API documentation is essential for enabling seamless integration and adoption of your services. One effective way to enhance the accessibility and professionalism of your API documentation is by hosting it on a custom domain. This guide will walk you through the benefits and steps involved in setting up your API documentation with a custom domain.

Significance of Custom Domain for API Documentation

API documentation is a critical component for developers who rely on your APIs to build applications. Hosting this documentation on a custom domain not only reinforces your brand identity but also provides a user-friendly and professional experience for your users. By using a custom domain, you can ensure that your API documentation is easily accessible and reflects the quality of your service.

Benefits of Hosting API Documentation on a Custom Domain

Brand Consistency

A custom domain allows you to align your API documentation with your brand’s identity. It creates a cohesive experience for your users, reinforcing your brand's credibility and professionalism.

Improved Accessibility

Using a custom domain makes your API documentation easier to remember and access. Instead of a generic or lengthy URL, users can quickly navigate to a branded domain, improving the overall user experience.

Enhanced Security

Custom domains often come with enhanced security features, such as SSL certificates, that protect your users’ data and build trust in your service. Secure documentation hosting ensures that users can safely access and interact with your API documentation.

SEO Benefits

A custom domain can improve your search engine rankings, making your documentation more discoverable. By optimizing your API documentation for search engines, you can attract more developers to your platform.

Steps to Host API Documentation on a Custom Domain

Step 1. Choose a Documentation Hosting Platform

Several platforms, such as SwaggerHub, Redocly, and Apidog, allow you to host API documentation. Choose one that fits your needs and supports custom domain configuration.

Step 2. Set Up Your Custom Domain

Once you've chosen a platform, follow these general steps to configure your custom domain:

a. Purchase a Domain Name: If you don't already have a domain, purchase one from a domain registrar like GoDaddy, Namecheap, or Google Domains.

b. Configure DNS Settings: Log in to your domain registrar and navigate to the DNS management section. Create a CNAME record that points your custom domain to the documentation hosting platform's domain. For example, if your documentation is hosted at docs.yourapi.com, create a CNAME record pointing docs.yourapi.com to yourapi.docs.hostingplatform.com.

c. Verify Domain Ownership: Some platforms require you to verify domain ownership. This process usually involves adding a TXT record to your DNS settings with a verification code provided by the platform.

d. Configure HTTPS (SSL): Ensure your custom domain supports HTTPS for secure connections. Many hosting platforms offer automatic SSL certificates, but you may need to manually configure it in some cases.

Step 3. Deploy Your API Documentation

With your domain configured, deploy your API documentation to the hosting platform. Follow the platform-specific instructions for uploading your documentation files or connecting your repository.

Step 4. Test and Verify

Once deployed, access your API documentation via your custom domain to ensure everything is working correctly. Check for any broken links, formatting issues, or SSL certificate errors.

Design, Auto-generate, and Host API Documentation using Apidog

In the digital economy, APIs (Application Programming Interfaces) are crucial for enabling software applications to communicate with each other. Whether you're a startup or an enterprise, robust API documentation is essential for helping developers understand and use your APIs efficiently.

Among all the API documentation hosting platforms, Apidog stands out as a versatile platform that supports the entire lifecycle of API documentation—from design to auto-generation and hosting. Here’s why it should be your go-to tool.

1. Comprehensive API Design Tool

Apidog provides a robust design tool that allows you to create detailed API specifications. Whether you're starting from scratch or refining an existing API, Apidog's design tool offers:

• Visual Interface: An intuitive drag-and-drop interface for designing API endpoints, request/response schemas, and data models.
• Standard Compliance: Automatically ensures your API designs comply with industry standards like OpenAPI and Swagger.
• Collaborative Design: Enables team members to collaborate in real-time, ensuring your API design evolves with collective input.

2. Auto-Generate Documentation

One of Apidog’s standout features is its ability to auto-generate API documentation directly from your API specifications. This ensures that your documentation is always up-to-date and consistent with the current state of your API.

• Synchronization: Automatically updates the documentation whenever changes are made to the API design.
• Rich Documentation: Includes detailed descriptions, data models, example requests and responses, and authentication methods.
• Customization: Allows you to add custom notes using markdown, code examples, and metadata to enhance the documentation.

3. Interactive API Documentation

Apidog supports interactive documentation, allowing developers to test API endpoints directly from the documentation itself. This hands-on feature improves the developer experience and makes them more likely to adopt and use your API:

• Try-It-Out Feature: Let developers execute API requests and view responses directly within the online documentation.
• Authentication Handling: Manages API keys, tokens, and other authentication methods seamlessly.

4. Easy Hosting and Custom Domains

Apidog not only helps you design and generate documentation but also offers robust hosting solutions. You can host your documentation on a custom domain, enhancing your brand’s professionalism and centralizing your resources.

• Custom Domains: Host your documentation on a domain that aligns with your brand (e.g., docs.yourcompany.com).
• Security: Provides SSL encryption, user authentication, and permissions management to keep your documentation secure.

5. Seamless Integration with Development Tools

Apidog integrates seamlessly with various development and CI/CD tools to streamline your workflow. This compatibility ensures that your documentation is part of your broader development lifecycle:

• Version Control Systems: Integrates with GitHub, GitLab, and Bitbucket.
• CI/CD Pipelines: Compatible with Jenkins, CircleCI, and other CI/CD tools.

6. Robust Collaboration Features

For teams, collaboration is key to maintaining accurate and comprehensive documentation. Apidog supports multiple collaborators and provides features to ensure that changes are tracked and managed efficiently:

• Real-Time Editing: Multiple team members can work on the documentation simultaneously.
• Version Control: Track changes, revert to previous versions and manage documentation updates seamlessly.

Setting up Custom Domains for API Documents

Apidog offers the ability to use a custom domain for your API documentation. Here is a step-by-step guide on how you can do it:

Step 1. Initiating the Custom Domain Setup

Custom domains can be configured by users with owner or admin access. Follow these steps to get started:

1. Access Share Module

Navigate to the project’s share module in Apidog.

• Click on the Share Docs menu in the sidebar.
• Go to the Publish settings page in the secondary menu.

2. Initiate Custom Domain Setup

• In the Custom Domain section, click the Edit button.

You will see two options for setting a custom domain:

• CNAME: Recommended for its simplicity and flexibility.
• Reverse Proxy: More advanced, suitable for users familiar with CDN or reverse proxy setups.

Step 2. Configure Custom Domain for API Documents

Method 1: Configuring Custom Domain using CNAME

1. Configure a CNAME Record

Configuration of DNS happens at your DNS provider’s control panel. Here’s a generic walkthrough:

• Type: Choose CNAME.
• Name or DNS entry: Enter your subdomain (e.g., docs.example.com or just docs if the domain is implied).
• Target or value or destination: This is where the subdomain should be pointed, which can be found in Apidog’s publish settings when you choose the CNAME option. It will look something like: {projectId}.apidog.io (e.g., 12345678.apidog.io).
• TTL(Time To Live): Set to Auto or leave the default value if you’re uncertain.

Ensure no conflicting records (like A, AAAA, TXT) exist for the chosen subdomain. Remove these if necessary before adding your CNAME record.

Special Note for Cloudflare Users:

If using Cloudflare:

• Ensure that Cloudflare’s proxying is disabled.
• This prevents DNS target obfuscation and enables Apidog to perform routine domain checks.

2. Waiting for DNS Propagation

DNS changes typically take between 10 minutes to 48 hours to propagate. To track the progress, you can use a DNS lookup tool like WhatsMyDNS. Enter your subdomain, choose CNAME, and hit search to see real-time propagation updates.

Method 2: Configure Custom Domain Using Web Server

This step is relevant if you choose the Reverse Proxy option.

For users setting up their reverse proxy server, here’s how to configure Nginx:

1. Nginx Configuration:

server {
    ...
    location / {
        proxy_pass  http://{projectId}.apidog.io;
        proxy_set_header X-Apidog-Project-ID {projectId};
        proxy_set_header Host docs.example.com;
        ...
    }
    ...
}

Caddy configuration example:

:8080 {
        handle_path /* {
                reverse_proxy http://{projectId.apidog.io {
                        header_up X-Apidog-Project-ID {projectId}
                        header_up Host "docs.example.com"
                }

      }
}
}

2. Set up DNS Record:

Configure the DNS record for your custom domain name to point to your reverse proxy server.

Method 3: Configure Custom Domain Using a CDN

This step is relevant if you choose the Reverse Proxy option.

1. Setting up AWS CloudFront as Reverse Proxy

You can use AWS CloudFront or other CDN services as your reverse proxy server. We will use AWS CloudFront as the reverse proxy server in this example.

Log in to AWS and navigate to CloudFront. Click Create Distribution.

Configure the distribution settings:

• Origin Domain Name: {projectId}.apidog.io
• Name: A description for the origin, which must be unique, allows you to differentiate between multiple origins within the same distribution.
• Origin Protocol Policy: Set to HTTP Only.
• Alternate Domain Names (CNAMEs): Your custom domain name.
• SSL Certificate: Choose the SSL certificate from AWS Certificate Manager (ACM).

Origin Custom Headers:

• Header Name: X-Apidog-Project-ID
• Value: {projectId}

Default Cache Behavior Settings:

• Viewer Protocol Policy: Redirect HTTP to HTTPS
• Allowed HTTP Methods: Select GET, HEAD, OPTIONS, PUT, POST, PATCH, DELETE.
• Cache and origin request settings: Use legacy cache settings, selecting All for Headers, Query strings, and Cookies.

2. Finish Creating Distribution:

Click Create Distribution at the bottom of the page. The distribution status will show as "In progress" until deployed.

3. DNS Setup:

Add a CNAME record in your DNS provider’s control panel pointing to your CloudFront domain name.

Embedding API Document into Your Website's Subdirectory

Available in Apidog version ≥ 2.5.24. You can embed the API documentation into a subdirectory (e.g., Your-Website.com/api-docs).

1. Enable Reverse Proxy in Apidog:

• Go to Custom Domain settings.
• Click on Reverse Proxy and switch on Use subdirectory.

2. Modify Web Server (e.g. Nginx) Configuration:

server {
    ...
    location /api-docs/ {
        proxy_pass  http://{projectId}.apidog.io/;
        proxy_set_header X-Apidog-Project-ID {projectId};
        proxy_set_header Host docs.example.com;
        ...
    }
    ...
}

Custom Domain | Apidog

Learn how to set a custom domain for your API documentation.

Apidog Logo

Best Practices for API Documentation

• Consistent Branding: Ensure that your custom domain and the content of your API documentation align with your brand’s style and messaging.
• Be Comprehensive: Include detailed explanations, code examples, and use cases.
• Provide Clear Navigation: Ensure your documentation is easy to navigate with a clear structure and search functionality.
• Regular Updates: Keep your documentation up-to-date with the latest API changes and enhancements.
• Monitoring: Regularly monitor your custom domain for any issues or downtime to maintain a seamless user experience.
• User Feedback: Encourage users to provide feedback on your documentation to improve its clarity and usability continuously.

Conclusion

In the highly competitive field of software development, providing clear and accessible API documentation is crucial for the seamless integration and adoption of your services. Hosting your API documentation on a custom domain offers numerous benefits, including enhanced brand consistency, improved accessibility, increased security, and better SEO performance. By following the steps outlined in this guide, you can easily set up and deploy your API documentation on a custom domain, thereby improving the user experience and reinforcing your brand's professionalism.

Platforms like Apidog make this process even more straightforward by offering comprehensive tools for designing, auto-generating, and hosting API documentation. With features such as a robust design interface, interactive documentation, seamless integration with development tools, and strong collaboration capabilities, Apidog stands out as a versatile solution for managing your API documentation needs.

Ultimately, investing in a custom domain for your API documentation not only elevates the perception of your service but also ensures that developers can access and utilize your APIs efficiently. By prioritizing quality documentation and leveraging tools like Apidog, you can foster greater trust and engagement with your developer community, driving the success and adoption of your APIs.