Hosting Swagger-UI using GitHub Pages

At my workplace we are using Swagger-UI to document and manually test our REST APIs.

That means that we have set up some hosts so serve this. I have for some time been pondering whether it would be possible to serve this via GitHub, GitHub Pages in particular - I was thinking about even writing up my own variation, believing this would be the path ahead.

Investigating something different I fell over the following section in the documentation:

Plain old HTML/CSS/JS (Standalone)

The folder /dist includes all the HTML, CSS and JS files needed to > run SwaggerUI on a static website or CMS, without requiring NPM.

1. Download the latest release.


2. Copy the contents of the /dist folder to your server.


3. Open swagger-initializer.js in your text editor and replace
   "





I am going to echo the contents of the README from the repository here.





The repository ended up being structured as follows:






• 
  api-docs/ - directory containing the Swagger-UI


• 
  swagger.json - the OpenAPI/Swagger definition


• 
  README.md - this file (documentation describing the experiment)






When the repository was set up the following steps were taken:





First a directory for the Swagger-UI was created:








CODE Kopieren
mkdir api-docs









The Swagger-UI was downloaded and the relevant files where extracted into the api-docs/ directory:








CODE Kopieren
curl -X GET https://github.com/swagger-api/swagger-ui/releases/tag/v5.17.14









Do note the version number was the one available at the time of the experiment, do fetch the newest version available.





The files were unpacked:








CODE Kopieren
tar xvzf swagger-ui-5.17.14.tar.gz









The files was copied to the api-docs/ directory created above:








CODE Kopieren
cd swagger-ui-5.17.14

cd dist # navigate to the dist directory

cp -r . ../../api-docs # copy the files to the api-docs directory recursively

cd ../../ # skip back to the root of the repository









You can call the directory what you want. The name api-docs/ is just a suggestion.





The dist/ directory contains the Swagger-UI files, which can be used to serve the Swagger documentation as a static site.





From the " with the URL for your OpenAPI 3.0 spec.

Since I did not have anything sharable at the time of the expirment, only work related definitiosn, I choose to use the Swagger Petstore example:

To demonstrate that it is possible to use a local file, I used the swagger.json file in the repository.

First I dowmloaded the referenced file:

curl -X GET -o swagger.json https://petstore.swagger.io/v2/swagger.json

I edited the swagger-initializer.js file and added the path to the swagger.json file:

url: "../swagger.json",

Since we can

The Swagger-UI was now served as a static site using GitHub Pages.

Do note GitHub Pages should be enabled for the repository.

It worked as expected and fetching the swagger.json file from the repository in addition to the remote file (https://petstore.swagger.io/v2/swagger.json) and the file we service our selves (https://jonasbn.github.io/gh-pages-swagger-ui-experiment/swagger.json).

I tested calling a few API endpoints directly from the page and it works as expected - the setup does make it much easier to have both the specification under version control and to serve it with the Swagger-UI, without having to set up a separate server or a service to serve the Swagger-UI, like: which is deprecated, so I am looking for an alternative.

At some point I need to work out the process of updating the contents of the api-docs/ directory in the repository from the Swagger-UI dist/ directory, so I can keep the Swagger-UI up-to-date.

For now I have signed for notifications on releases and security announcements with the repository.

Finally, a caveat