Publish docs sites

Publishing a docs site is distinct from using theQuick Sharefeature. WhileQuick Sharegenerates a shareable link for internal and external partners, serving as a temporary communication method, it’s not intended for long-term use.

In contrast, the Publish Docs Sites feature allows for more robust customization. It lets you personalize the domain name, page design, navigation, and more. This feature is ideal when you need to make your API documentation publicly accessible on your official website.

Publish your docs site

Click on the default main site and then click thePublishbutton.

Docs site visibility setting

Apidog version must be ≥ 2.7.15.

After clicking on thePublish button, you can easily control the visibility of your published doc sites based on your needs. Simply click thePublish right nowbutton to make your site live.

Public

Your doc sites will be accessible to all internet users. You can also choose to publish your API documentation on API Hub, a platform operated by Apidog that helps users discover and explore APIs.

Password protected

If you prefer to secure your API documentations with passwords, enablePassword protectedand set a password — either by creating your own or generating a random one.

IP Allowlist

Restrict access to your doc site to only the specific IP addresses or ranges that you configure.

Email Allowlist

Only the emails on your configured email allowlist can access your doc sites by verifying their emails through verification codes. The email allowlist supports wildcards, making it easier to manage access for enterprise emails.

If you want users to authenticate through your own login system before accessing the online documentation site, you can enable the Custom Login Page feature.

Configuration Guide

Go to the visibility settings of the documentation site, select Custom Login Page, and fill in the following two fields:

JWT Secret: Used to verify the signature of the token. It must be the same as the secret your backend uses when issuing JWTs. You need to generate this secret yourself.

Login URL: When users access the online documentation site, they will be redirected to this URL. You must host a login page at this address and implement authentication and token generation on your backend.

This login page is not provided by Apidog — you need to build and host your own.

Authentication Workflow

JWT (JSON Web Token) is an open standard for user authentication. Your login system should follow the flow below:

A user visits the online documentation site published by Apidog (e.g., https://xxxxx.apidog.io);

The system automatically redirects them to your configured login page (e.g., http://localhost:3000);

The user enters their credentials and submits the form;

Your backend verifies the user credentials;

Upon successful authentication, your backend generates a JWT signed using your configured secret (e.g., pJRdFC3amihQdWbHvUXNZG9WzYdEGHao);

Then, redirect the user back to the documentation site (e.g., https://xxxxx.apidog.io) and include the token as a query parameter named auth_token, like so:

Apidog will automatically validate the token. If successful, the user can access the documentation content.

The login flow is illustrated in the diagram below:

Important Notes

JWTs must be generated by your backend and signed using the secret configured in Apidog;

The JWT should be passed back to the documentation site via the auth_token URL parameter;

Apidog will automatically parse and validate the token;

The documentation site URL can be the default address provided by Apidog or a custom domain you configured.

FAQ

What tech stack can I use for the login page?

There are no restrictions. As long as your backend can handle POST login requests and return a URL containing auth_token, it will work. Node.js, PHP, Python, Go, etc., are all supported.

Is there a sample project available?

Publishing scope

By default, the scope for publishing documentation is set to allSharedresources. You can configure this in theAPIs. For more details, please refer to visibility settings.

Release

You can create and publish multiple versions of your API documentation. Learn more about publishing API versions.

Domain

Apidog provided domain: Your document will have a default Apidog Subdomain, such as https://vhh2uhkjv7.apidog.io. You can also modify it manually. All Apidog documents use the apidog.io domain.

Custom Domain: You can bind the Apidog document to your own domain. Learn more about Custom domain.

domain settings for API documentations.jpg

Customize

You can customize appearance and layouts for API documentations.

Appearance

Basic info

You can switch to Basic Info to set various basic options for the API documentation, including:

Title

Logo

Favicon

Primary color

Language

Light/Dark mode

Content display

InContent display, you can customize which fields to display in API documentation, including:

Base URL

Owners

Show 'Last Modified' Time above Endpoint Description

Show 'Last Modified' Time at Document's End

Request samples

OperationId

Advanced settings

You can choose to hide some information that you don't want users get accessed to, such as:

Hide 'Powered by Apidog' (Available for Professional or higher plans)

Hide 'Run in Apidog' Button (Available for Professional or higher plans)

Show 'Try it out' Button

Allow 'Export', 'Clone' Data

You can customize the page layout with ease. Learn more about Custom layouts.

Advanced settings

Documentation search

While the published API documentation includes a built-in search feature by default, Apidog offers integration with Algolia to enhance search capabilities. Learn more about documentation Search.

CORS proxy

You can specify a CORS proxy to avoid issues caused by browser security restrictions. Learn more about CORS Proxy.

Google analytics

The Apidog doc sites now supports integration with Google Analytics. Learn more about integrating Google Analytics with Doc Sites.

Publish to API hub

You can choose to publish your docs on API Hub, an open platform operated by Apidog, designed specifically for sharing and exploring APIs.

Description

If the project has been published to the API Hub, then this description will be displayed on API Hub.

Allow 'Export', 'Clone' data

You can export the released documentation data in main branch.

Docs redirect rules

You can set up redirect rules to automatically redirect users to the correct documentation when URLs change, preventing broken links and ensuring a seamless experience.

URL & Slug rules

Define URL rules for your API documentations.

Publish multiple docs sites

To publish docs across different channels within the same project, you can create additional docs sites during publishing. For easier management, you can duplicate the main site’s configuration for each new site. Each sub-site can also have a unique custom domain name.

Only subsites let you set the visibility scope for published docs, allowing you to choose which resources are publicly accessible.

Publish your docs site#

Docs site visibility setting#

Public#

Password protected#

IP Allowlist#

Email Allowlist#

Custom Login Page#

Publishing scope#

Release#

Domain#

Customize#

Appearance#

Basic info#

Content display#

Advanced settings#

Layout & Navigation#

Advanced settings#

Documentation search#

CORS proxy#

Google analytics#

Publish to API hub#

Description#

Allow 'Export', 'Clone' data#

Docs redirect rules#

URL & Slug rules#

Publish multiple docs sites#

Publish your docs site

Docs site visibility setting

Public

Password protected

IP Allowlist

Email Allowlist

Custom Login Page

Publishing scope

Release

Domain

Customize

Appearance

Basic info

Content display

Advanced settings

Layout & Navigation

Advanced settings

Documentation search

CORS proxy

Google analytics

Publish to API hub

Description

Allow 'Export', 'Clone' data

Docs redirect rules

URL & Slug rules

Publish multiple docs sites