Skip to content

Same-origin docs by design

Register mounts the spec and the docs UI onto your server's mux — the same server that handles the API. That is a deliberate design choice, not an incidental one, and it is what makes the interactive "try it" console work with no extra configuration.

The problem with hosting docs elsewhere

A common pattern is to publish API docs on a separate static host (a docs site, an S3 bucket, a CDN). It renders the spec fine — but the moment a reader clicks "try it", the console issues a request from the docs origin to the API origin. That is a cross-origin request, so it is governed by CORS: the API must send Access-Control-Allow-Origin (and, for credentialed calls, the matching allow-credentials and allow-headers) for the browser to let the response through. Getting that right — especially with auth — is fiddly and easy to misconfigure.

Same-origin removes the question

Because transport-openapi serves /openapi.yaml and /docs/ from the same server as the API, the try-it console calls the API same-origin. There is no cross-origin boundary, so:

  • No Access-Control-Allow-Origin needed for the console to read responses.
  • Credentialed "try it" calls work under the console's tryItCredentialsPolicy="same-origin" without extra allow-credentials wiring.
  • What a reader exercises in the console is exactly your live server — same host, same middleware, same auth — not a proxy or a mock.

The security-header default follows from this

Serving an interactive console from your own origin is powerful, so the handlers are wrapped with conservative security headers by default (nosniff, X-Frame-Options: DENY, frame-ancestors 'none', no-referrer). The console is same-origin with your API and hardened against being framed or sniffed — see Configure security headers. You can customise or opt out, but the safe posture is the default.