How to Host an OpenAPI Spec for Free

Any viewer that loads a spec from a URL — GetMan included — needs that file served from somewhere with a stable address and, critically, the right CORS headers. You don’t need dedicated hosting for this; a few free options already cover it.

Option 1: raw.githubusercontent.com

If your spec already lives in a GitHub repo, the simplest option is pointing at its raw content URL directly — no extra setup required:

https://raw.githubusercontent.com/<user>/<repo>/<branch>/openapi.json

This is the easiest option to get working and the one worth trying first, because raw.githubusercontent.com sends permissive CORS headers by default — a browser-based viewer can fetch it cross-origin without extra configuration. The tradeoff: it’s tied to a specific branch and commit path, so if you rename the file or branch you’ll need to update the URL everywhere it’s referenced.

Option 2: GitHub Pages

If you’d rather have a clean, versioned URL that doesn’t expose your repo’s raw file structure, GitHub Pages serves static files — including a spec — from a repo for free. This also gives you a place to host the docs page itself alongside the spec, not just the spec file in isolation. The GitHub Pages guide covers the full setup, including keeping the committed spec in sync with one generated by your build.

Option 3: GitHub Gist

For a spec that isn’t part of a full repo — a quick prototype, a spec you’re sharing for review — a public Gist works. Use the raw URL of a specific file in the Gist, not the Gist’s HTML page URL:

https://gist.githubusercontent.com/<user>/<gist-id>/raw/openapi.json

Gist raw URLs are versioned by commit hash unless you use the raw alias shown above, which always resolves to the latest revision — convenient for iterating, but worth knowing if you need a link that’s guaranteed to point at one exact spec version forever.

The CORS gotcha

This is where most “just host it somewhere free” attempts break. A file being publicly reachable in a browser tab doesn’t mean a script on a different origin can fetch it — that requires the response to include an Access-Control-Allow-Origin header. All three options above send the right header by default. Plenty of other free static hosts don’t, which shows up as a spec that opens fine when you visit the URL directly but fails silently (or with a console CORS error) when a viewer tries to fetch it programmatically. If you switch hosts later and docs stop loading, check the response headers before assuming the spec itself is broken.

Pointing GetMan at it

Once the spec has a stable, CORS-friendly URL, wiring it up is one line:

<script>
  GetMan.launch(document.getElementById('api-docs'), {
    url: 'https://raw.githubusercontent.com/<user>/<repo>/main/openapi.json',
  });
</script>

Full setup and options are in the docs.