explore-openapi

A small script that turns GitHub's REST API OpenAPI spec into a static, browsable reference site that includes every endpoint, grouped by tag.

Live site: https://kapunahelewong.github.io/explore-openapi/

What it does

generate_docs_site.py fetches GitHub's published api.github.com.json OpenAPI spec, groups all ~1,200 endpoints by tag (issues, repos, actions, etc. for 47 tags in total), and renders one HTML page per tag into docs/. Each doc features each endpoint's method, path, description, parameters, and possible responses, plus a linked table of contents. docs/index.html lists every tag with a description and endpoint count, linking out to its page. GitHub Pages serves the site from the docs/ folder.

It's a small-scale version of what tools like Scalar, Redoc, or Swagger UI do at a much larger scale. I created this to play around.

Running it locally

python3 generate_docs_site.py

This regenerates docs/index.html plus one docs/{tag}.html file per tag, from whatever spec GitHub has published at the time you run it — no local copy of the spec is stored or required.

Keeping the site fresh

There's no automatic refresh — run python3 generate_docs_site.py locally whenever you want the site to reflect the latest published spec, then commit and push docs/. GitHub Pages redeploys automatically from main.

A smaller, single-tag version

examples/single-tag-version/ keeps an earlier version of generate_docs_site.py, from before it grew to cover every tag — it documents just one tag (issues) into a single index.html. If the full multi-page generator feels like a lot, start there. This file has lots of comments to clarify what the Python is doing under the hood.