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 \
  -e DOC_EXPANSION=none \
  -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.

Using Multiple Files

You don't have to have everything in a single swagger file. If you have broken things up into a group of files, you may wish to use the following instead:

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

The above example assumes you have a local folder called files which contains a root document called openapi.json.

Obviously, when you are breaking things up over multiple files, you need the references to use relative paths. E.g. one might have the following in the root openapi.json file:

    "paths": {
        "/pets/{petId}": {
            "$ref": "./paths/pets.json"
        }
    }

In this case, I have a subfolder called paths, within my top level files directory.

Having Issues Using Multiple Files?

If you are confused about breaking things up into multiple files, I suggest you read How to split a large OpenAPI document into multiple files. I found that I could mix/match YAML and JSON files without issue, and that even though the Docker environment file may be called SWAGGER_JSON, it can point to a YAML file instead and still work.

Custom Configuring

There is a bunch of documentation on how you can configure various things about the UI. This is where I found out that setting the DOC_EXPANSION variable allowed me to have swagger UI load up with everything collapsed by default.

Docker-Compose File

Below is the equivalent docker-compose.yml file if you don't wish to use the docker run command.

version: "3"

services:
  app:
    container_name: swagger
    image: swaggerapi/swagger-ui
    restart: always
    environment:
      - SWAGGER_JSON=/swagger.json
      - DOC_EXPANSION=none # optionally set to list, or full
    volumes:
      - ./src/swagger.json:/swagger.json:ro
    ports:
      - "80:8080"

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