How-to: use swagger-ui to view an open-api yaml file

Swagger and open-api are popular for publishing API documentation. However, what do you do if the API docs are given to you as a YAML file instead of a nicely formatted web page? Well, you don't need to suffer with opening it in VI or Notepad to read it.

Swagger supports an open source project named swagger-ui that produces a nicely formatted web interface from the spec. They also publishes a ready to use docker container for it.

You’ll want to install docker desktop as it includes the cli & the docker daemon.

Lets say the file I recevied is named "my-api.yaml". I created a directory named open-apis in my home directory, and placed the yaml file in it. You can run the swagger-ui docker container with a mount point pointing to open-apis as follows:

> docker run -p 5000:8080 --name swaggerui -v C:/Users/ram/open-apis:/open-apis -e SWAGGER_JSON=/open-apis/my-api.yaml swaggerapi/swagger-ui

Deconstructed:

-p 5000:8080 sets up https://localhost:5000 to point to port 8080 in the container (where the swagger-ui webapp runs);

--name swaggerui names the container for your convenience with docker command line interface (cli)

-v C:/Users/ram/open-apis:/open-apis sets up a mount point within the container where /open-apis points to C:/Users/ram/open-apis on your computer, aka the host. This is how the program running within the container can read the yaml file you saved. Use the absolute path to whatever directory you saved the yaml file in.

-e SWAGGER_JSON=/open-apis/my-api.yaml sets an environment variable instructing the swagger-ui webapp to start with /open-apis/my-api.yaml by default.

Lastly, the parameter swaggerapi/swagger-ui refers to the image published by the swagger-ui team on docker hub.