Can I password-protect Swagger UI instead?

Swagger UI doesn't have built-in auth. You can add HTTP basic auth at the server level (Nginx, Apache), but that's a shared password, not identity-aware. Anyone who has the password can share it, and there's no per-user audit trail.

Does this work with OpenAPI 3.1?

Yes. Both Swagger UI and Redoc support OpenAPI 3.1. Generate the HTML bundle from your spec file and publish it; display.dev serves whatever HTML you provide.

Can I restrict API docs to specific teams within the company?

Not yet at the subdomain level; the current access model is domain-based (all `@yourcompany.com` emails get access). For team-level restrictions, you can create separate artifacts per team and share only the relevant URL with each audience. On Pro you can also mark an artifact private and invite specific people.

Do viewers need a display.dev account or an API key?

No. Publishers authenticate (via `dsp login` or a scoped API key in CI); viewers just open the link and sign in with their company Google or Microsoft account. On the Free plan viewers verify with a one-time passcode (a six-digit code by email). Nobody needs a display.dev seat to read the docs.

Can I keep the same URL every time the spec changes?

Yes. Republish with `--id ` and `--base-version`, and the artifact updates in place at the same URL. Each publish is retained as a version (90-day audit logs on Pro show who published what and when).

Does the try-it-out console work behind the gate?

Yes. display.dev serves the full HTML, so Swagger UI's interactive request console runs exactly as it does when self-hosted. Requests go to whatever server URLs your OpenAPI spec declares.

Host Swagger UI Behind Company Auth (Without Cloudflare Access)

Swagger UI and Redoc both render an OpenAPI specification into a browsable API reference. Both can build a standalone HTML file. The hard part is the same one every internal tool hits: it shouldn't be public, but standing up authentication in front of a static page usually means a VPN, a reverse proxy, or a per-seat access product. This guide skips all of that: build the HTML once, publish it, and the reference lives behind your company's identity provider.

The problem

Internal API documentation shouldn't be public. Your API endpoints, authentication flows, request/response schemas, and error codes are internal information: useful to your engineers, valuable to anyone trying to reverse-engineer your product.

The standard approaches to protecting it are expensive or complex:

Nginx behind VPN: Requires every API consumer to be on the VPN. Mobile developers, remote contractors, and teams on different network segments all hit friction.
Cloudflare Pages + Access: ~$700/month for 100 users at $7/user/month above the free tier (Cloudflare Zero Trust pricing). 2–4 hours of setup. Per-seat pricing punishes broad access.
Azure Static Web Apps: Free tier is Microsoft-only. Standard tier requires Azure expertise.
Self-hosted Swagger UI behind HTTP basic auth: A shared password, not identity-aware. Anyone with the password can share it.

display.dev: generate a static Swagger UI bundle, publish it, get a company-gated URL.

Generate a static Swagger UI file

From an OpenAPI spec file:

npm install swagger-ui-dist
 
node -e "
const fs = require('fs');
const path = require('path');
const swaggerUiDist = require('swagger-ui-dist');
const spec = JSON.parse(fs.readFileSync('./openapi.json', 'utf8'));
 
const html = \`<!DOCTYPE html>
<html>
<head>
  <title>API Documentation</title>
  <link rel='stylesheet' type='text/css' href='https://unpkg.com/swagger-ui-dist@5/swagger-ui.css'>
</head>
<body>
  <div id='swagger-ui'></div>
  <script src='https://unpkg.com/swagger-ui-dist@5/swagger-ui-bundle.js'></script>
  <script src='https://unpkg.com/swagger-ui-dist@5/swagger-ui-standalone-preset.js'></script>
  <script>
    SwaggerUIBundle({
      spec: \${JSON.stringify(spec)},
      dom_id: '#swagger-ui',
      presets: [SwaggerUIBundle.presets.apis, SwaggerUIStandalonePreset],
      layout: 'StandaloneLayout'
    })
  </script>
</body>
</html>\`;
 
fs.writeFileSync('./api-docs.html', html);
"

Or use Redoc (simpler for read-only documentation):

npx @redocly/cli build-docs openapi.json -o api-docs.html

Publish with display.dev

dsp publish ./api-docs.html --name "internal-api-docs"

Share the URL in your onboarding docs, Notion, or Slack. Engineers authenticate with their company email and see the full interactive API reference: try-it-out, request/response schemas, and authentication flows.

Auto-update when the spec changes

name: Publish API Docs
 
on:
  push:
    branches: [main]
    paths: ['openapi.json', 'openapi.yaml']
 
jobs:
  publish:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Generate Swagger UI
        run: npx @redocly/cli build-docs openapi.json -o api-docs.html
      - name: Publish docs
        run: |
          npm install -g @displaydev/cli
          BASE_VERSION=$(dsp get "${{ vars.DISPLAY_ARTIFACT_ID }}" | jq -r .currentVersion)
          dsp publish ./api-docs.html --id "${{ vars.DISPLAY_ARTIFACT_ID }}" --base-version "$BASE_VERSION"
        env:
          DISPLAYDEV_API_KEY: ${{ secrets.DISPLAYDEV_API_KEY }}

Every time openapi.json changes on main, the published API docs update automatically using the artifact ID stored in DISPLAY_ARTIFACT_ID. The URL stays the same, so bookmarks and Slack links keep working. --base-version guards against a concurrent publish being overwritten silently. For the general CI pattern, see publishing HTML from GitHub Actions.

Comparison

	Nginx + VPN	Cloudflare Pages + Access	display.dev
Monthly cost	$50+ VPS + maintenance	~$700 (100 users)	€49
Setup time	Hours	2–4 hours	15 min
Requires VPN client	✅	❌	❌
Company identity auth	✅ (via LDAP/VPN)	✅	✅
Google + Microsoft SSO	✅ (with config)	✅	✅
Maintenance	High	Medium	None

With more than half of professional developers using AI coding tools daily (Stack Overflow 2025 Developer Survey), API references are increasingly generated and regenerated by agents straight from the spec, which makes a one-command publish that keeps the same URL more useful than a hand-maintained deployment.

The problem

Generate a static Swagger UI file

Publish with display.dev

Auto-update when the spec changes

Comparison

FAQ