Document Your API with Swagger And Docker

When developing an API, it's good to map out what the endpoints are going to be, before actually building the API. This way other developers will know how they will be able to interface with your API, even before it's built. If you already have an API, it's useful to document the endpoints in a manner that makes it easy for others to integrate with your API without having to perform a lot of guesswork and reading.

Steps

To achieve this, I use a PHP package (I created) to generate a swagger.json file. However, if you want to, you can read the specifications to manually type out your own swagger.json file. The swagger.json file is just a JSON file that describes your API. I developed the package to make it much easier, and prevent myself having to look things up all the time. I will include a video demonstration at a later date.

Once you have generated your swagger.json file you can use docker to deploy an intuitive website (swagger UI) that will use your specification, and that others can use to see how your API works, and even try it out.

docker run \
  --name swaggerui \
  -p 80:8080 \
  -e SWAGGER_JSON=/swagger.json \
  -v `pwd`/swagger.json:/swagger.json:ro \
  swaggerapi/swagger-ui

This script expects to be run from within the folder that contains your swagger.json file.

Custom Configuring

There is a bunch of documentation on how you can configure various things about the UI. You could create a configuration document or pass query parameters. For example, the following will load the page with everything collapsed:

http://swagger.my.domain.com/?docExpansion=none

Alternative - Redoc

Alternatively, you can pass the swagger.json to Redoc for a different look:

docker run -d \
  --restart=always \
  -p 80:80 \
  -v $(pwd)/swagger.json:/usr/share/nginx/html/swagger.json \
  -e SPEC_URL=swagger.json \
  redocly/redoc

Offline Documentation

If you want to generate files you can send someone, rather than having to host a website, then you can use the Redoc CLI tool.

First, install the CLI tool through NPM:

sudo npm i -g redoc-cli

Then you can generate the documentation with:

redoc-cli bundle -o docs.html swagger.json