swagger-github-pages and hosting Swagger UI documentation on GitHub Pages

What the template actually contains

The repository is titled as a guide to hosting Swagger API documentation with GitHub Pages, and its own description calls it a template for using Swagger UI to dynamically generate documentation for an API and host it for free with GitHub Pages.

The template is a working site rather than a script. The top-level entries are a .github/ directory, a LICENSE, the README.md, a dist/ directory, an index.html at the root, a screenshots/ directory, a file called swagger-ui.version, and a swagger.yaml file.

Those four files at the root are the design. Swagger UI is normally distributed as a set of static assets, and the usual way to use it is to serve those assets from somewhere and point a page at them. This template inverts that: the whole distribution is committed into the repository, the initializer file is committed with it, the example specification is committed next to it, and GitHub Pages serves the repository root as a static site. There is no build step and no runtime dependency on the CDN, because the assets are already in the tree.

The swagger-ui.version file is the piece that makes the update workflow work, and its presence at the root is the reason the repository can tell which upstream release it is carrying.

For the reader, the practical distinction is that this is a fork-and-edit starting point rather than a dependency you install. You get a repository whose contents you own, and the cost of that ownership is that keeping the vendored assets current becomes your problem unless the included workflow handles it for you.

The three-step route through the template button

The README gives a short path for most people, and it is worth reading because the number of steps is the selling point.

Step one is to click the Use this template button above to create a new repository from this template. That is the GitHub mechanism for taking a template repository as the starting point of a new one of your own, and it means you do not fork, you start clean.

Step two is to go to the settings for your repository at the address given in the README and enable GitHub Pages. The screenshot in the repository shows exactly which setting this is, which matters because GitHub Pages is configured in repository settings and the source of the pages can be a branch or a GitHub Actions workflow depending on how your account is set up.

Step three is to browse to the Swagger documentation at the user and repository address given in the README.

That is the whole flow for a template user, and the only thing the template asks of you is a specification file.

The example API specification used by the repository can be seen hosted at the author's own Pages URL, and that link is the fastest way to see what the finished result looks like before you create anything. It is also a useful reference for what the default page renders, since the committed swagger.yaml is the example document and the committed index.html is the page that loads it.

So the flow is: create the repository, turn on Pages, replace the example specification with your own, and the documentation is live. There is no npm install, no bundler and no server to run.

The manual route, and why dist/ has to sit at the root

For a repository you already have, the README documents a manual configuration path, and the reason it exists is that the assets have to be at a specific place on disk.

The steps start by downloading the latest stable release of Swagger UI from the upstream releases page, then extracting the contents and copying the dist directory to the root of your repository. The next step is moving index.html out of that directory and up to the root as well:

    mv dist/index.html .

That single move is the part people miss when they copy the directory and leave index.html inside it. The reason it has to be at the root is that Pages serves the repository root as the site root, so the page that Swagger UI loads has to be the site root page, and the assets it references are then reached through the dist/ path.

After that you copy the YAML specification file for your API to the root of your repository as well. Then you edit the initializer file and point it at that specification:

        window.ui = SwaggerUIBundle({
            url: "swagger.yaml",
        ...

Then you fix any references to files in the dist directory. The README shows the shape of those references, and they are the link and script tags that the page needs:

    ...
    <link rel="stylesheet" type="text/css" href="dist/swagger-ui.css" >
    <link rel="icon" type="image/png" href="dist/favicon-32x32.png" sizes="32x32" />
    <link rel="icon" type="image/png" href="dist/favicon-16x16.png" sizes="16x16" />    
    ...
    <script src="dist/swagger-ui-bundle.js"> </script>
    <script src="dist/swagger-ui-standalone-preset.js"> </script>    
    ...

Finally you enable GitHub Pages in the repository settings and browse to the Pages address, the same two steps as the template route.

The difference between the two routes is entirely in the first step. The template button commits a known-good copy of the distribution for you; the manual route is for a repository that already exists and where you would rather not create a new one.

The update workflow, and the pull request it opens

The template does not leave the vendored Swagger UI distribution at whatever version it was when you cloned it. The README states that the template will periodically auto-update the Swagger UI dependency and create a pull request, and points at the GitHub Actions workflow in .github/workflows/update-swagger.yml.

The mechanism is worth understanding precisely, because it changes the maintenance model. A scheduled workflow compares the version recorded in swagger-ui.version against the latest upstream release, and when they differ it downloads the new distribution, updates the committed files, and opens a pull request against your repository.

That means the upgrade arrives as a reviewable diff rather than as a silent change to a live site. The person or the team who owns the documentation repository sees a pull request that says, in effect, that Swagger UI has moved to a new version and these are the file changes, and then they decide whether to merge it. The alternative model, where a documentation site pulls the latest Swagger UI from a CDN at page load, means the site changes without anyone deciding that it should, which is convenient until it breaks.

The cost of the vendored model is that the assets are in your repository. They are a large set of minified JavaScript and CSS files, they are committed history that never shrinks, and every upgrade adds another set of files to the diff. For a small documentation repository that is a reasonable trade. For an organisation with a strict review process on third-party code, the pull requests are a genuine burden even though they are automated.

There is a second reason the pull request model is preferable to a CDN, and it is not about process. Swagger UI loads the API specification at runtime, and the relative url in the initializer means it loads swagger.yaml from the same site. Everything the page needs is served from one origin, so there is no dependency on a third-party CDN being reachable, and no cross-origin question about where the specification came from.

Where this approach stops working

Three limits follow from what the template is.

The first is that the specification has to live in the repository. The initializer points at a relative url, which means swagger.yaml is fetched from the site root. If your API definition lives in another repository, in a build artefact, or behind an internal URL, this template does not cover that case, and you would have to change the initializer to an absolute url, which means the documentation site then depends on that other origin being reachable and correctly configured for cross-origin requests.

The second is that the committed dist directory is a snapshot. It is convenient, because a Pages site needs static files and this supplies them, but it means the version of Swagger UI serving your documentation is whatever the last merged pull request set. There is no way to pick a version at request time, and there is no runtime fallback if a file in the distribution changes name between releases.

The third is that Pages is the hosting model. The URL pattern is a GitHub user and repository name, so the site lives at a github.io address rather than on a domain you control, unless you set up custom hosting yourself, which the README does not cover. There is also no server-side component, so anything the documentation page needs to compute has to happen in the browser.

The alternative worth comparing is the ordinary Swagger UI hosting arrangement, where the distribution is served from a CDN and the page points at a specification URL, or where a docs platform renders the OpenAPI document server-side. The difference in approach is ownership of the assets. Here you own a copy of the distribution and its upgrades arrive as diffs. In the CDN arrangement you own no assets and the version changes whenever the CDN changes. The first is better when a documentation site has to keep working and to be reviewable; the second is better when you want the newest UI with no repository chores and do not mind that the version is not yours to choose.

Editorial conclusion

swagger-github-pages is a good fit for a team that wants API documentation published at a GitHub Pages URL without standing up a docs server, because the whole dist directory is committed and the site is served straight from the repository. It is a poor fit if you want your OpenAPI document to live somewhere else and be pulled at render time, since the template expects the YAML file in the repository root and points Swagger UI at it with a relative url. Before adopting, read the update workflow linked as .github/workflows/update-swagger.yml, because an upstream Swagger UI release becomes a pull request against your repository that someone has to merge, and check that the committed dist directory is acceptable in your fork.

Frequently asked questions

Official sources

1. Issues
2. License: MIT
3. peter-evans/swagger-github-pages on GitHub
4. README