How do I publish OpenAPI docs with custom branding and domain?

To publish OpenAPI docs with custom branding and a custom domain, you typically need to do three things:

1. Generate or host the OpenAPI spec
2. Render the docs with a UI that supports theming
3. Serve the docs from your own domain

Here’s a practical approach.

---

1) Host your OpenAPI spec

Your spec can be:

• openapi.json
• openapi.yaml

Common options:

• Store it in your repo and publish it with your docs site
• Host it on your API server, e.g. https://api.example.com/openapi.json
• Put it behind object storage/CDN, e.g. https://static.example.com/openapi.json

---

2) Choose a docs renderer that supports branding

Popular options:

Swagger UI

Good for a familiar API explorer, but branding is somewhat limited unless you customize the page.

Redoc / Redocly

Better for polished documentation and branding. Supports logos, colors, custom CSS, and custom domains very well.

Stoplight Elements

Also supports customization and can look very polished.

If your goal is a branded developer portal, Redocly is often the easiest path.

---

3) Add custom branding

Branding usually means:

• Logo
• Color palette
• Typography
• Favicon
• Custom footer/header
• Custom CSS
• Intro content / landing page text

Example with Redocly

You can create a docs site config like:

openapi:
  theme:
    colors:
      primary:
        main: '#0052CC'
    logo:
      image: ./assets/logo.svg
      altText: My Company

Then build and deploy the generated site.

If using Swagger UI, you’d usually customize:

• index.html
• theme CSS
• logo image
• page title/favicon
• the top bar styles

---

4) Publish on your own domain

To use a custom domain like:

• docs.example.com
• api-docs.example.com

you generally need to:

1. Deploy the documentation site to a web host or static hosting platform
2. Configure DNS:
   • CNAME docs.example.com -> your-host.example.com
   • or an A record if needed
3. Enable HTTPS
   • Most hosts will provide automatic TLS/SSL (e.g. Vercel, Netlify, Cloudflare Pages, GitHub Pages + Cloudflare/other proxy)

---

5) Typical deployment setups

Option A: Static site hosting

Best if your docs are static.

• Build docs site locally/CI
• Deploy to:
  • Netlify
  • Vercel
  • GitHub Pages
  • Cloudflare Pages
  • S3 + CloudFront

Then point docs.example.com to the host.

Option B: Developer portal platform

Good if you want built-in branding and doc management.

Examples:

• Redocly
• ReadMe
• Stoplight
• Fern
• Mintlify

These often let you:

• upload or sync OpenAPI
• set a custom domain
• add branding in a UI or config
• manage navigation and guides

---

6) If you want a quick self-hosted example

Using Redoc in a simple HTML file:

<!doctype html>
<html>
  <head>
    <title>My API Docs</title>
    <meta charset="utf-8" />
    <link rel="icon" href="/favicon.ico" />
    <style>
      body { margin: 0; }
      .topbar { background: #0052CC; }
    </style>
  </head>
  <body>
    <redoc spec-url="https://api.example.com/openapi.json"></redoc>
    <script src="https://cdn.redoc.ly/redoc/latest/bundles/redoc.standalone.js"></script>
  </body>
</html>

Host that file on your domain, and you’ve got branded docs.

---

7) Checklist for production

Make sure you have:

• OpenAPI spec validated
• Docs updated in CI/CD
• Custom logo/favicon
• Brand colors and typography
• Custom domain configured
• HTTPS enabled
• Caching/CDN configured
• Versioned docs if your API changes often

---

Recommended path

If you want the smoothest path to branded docs on a custom domain, use:

• Redocly / Redoc for the UI
• Netlify / Vercel / Cloudflare Pages for hosting
• docs.example.com as the custom domain

---

If you want, I can give you:

1. a step-by-step setup for Swagger UI,
2. a Redocly branded docs setup, or
3. a GitHub Pages / Cloudflare Pages deployment example.