Generating documentation with Swagger UI

We now have a valid OpenAPI specification, which we can use to generate web-based API documentation using Swagger UI.

Adding the Swagger UI to our repository

The Swagger UI source files are located in the dist/ directory of the official repository. The official way of generating documentation UI for our own specification is to download the Swagger UI source files from github.com/swagger-api/swagger-ui/releases and statically serve the page at dist/index.html.

However, it'll more preferable to have the source code of the web UI in the same repository as our API. A naive approach would be to download the latest source files for Swagger UI from github.com/swagger-api/swagger-ui/releases, unpack the contents, and copy the contents of the dist/ directory into a docs/ directory inside our repository. However, this requires us to manually update the contents of the docs/ directory each time there's an update on Swagger UI; obviously, that's not ideal. Luckily...