Installing Swagger UI

Swagger UI can be installed/downloaded on various operating systems, but the best way could be using Docker. A Swagger UI Docker image is available on the Docker Hub. Then we can pass our Open API/Swagger file to the Docker container we run out of the image. Before that, we need to create a JSON file. The Swagger JSON file has few sections:

• info
• servers
• paths

Let's create a Swagger file with the preceding sections for the first service we built. Let's name it openapi.json:

{
  "openapi": "3.0.0",
  "info": {
    "title": "Mirror Finder Service",
    "description": "API service for finding the fastest mirror from the
     list of given mirror sites",
    "version": "0.1.1"
  },
  "servers": [
    {
      "url": "http://localhost:8000",
      "description": "Development server[Staging/Production are different
       from this]"
    }
  ],
  "paths": {
    "/fastest-mirror": {
      "get": {
        "summary": "Returns a fastest mirror site.",
        "description": "This call returns data of fastest reachable mirror
         site",
        "responses": {
          "200": {
            "description": "A JSON object of details",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "fastest_mirror": {
                      "type": "string"
                    },
                    "latency": {
                      "type": "integer"
                    }
                  }
                }
              }
            }
          }
        }
      }
    }
  }
}

Please notice how we defined the info, servers, and paths sections.

The openapi tag specifies the version of the API document we are using.

The info section has a service-related description. The servers section has the URL of the server where the application/server is running. We used localhost:8000 as we are running it locally. The paths section has information about all the API endpoints a service provides. It also has information about the request body, response type, and body structure. Even the possible error codes can be encapsulated into paths. 

Now let's install Swagger UI and make use of our Swagger file:

1. To install Swagger UI via Docker, run this command from your shell:

docker pull swaggerapi/swagger-ui

If you are on Windows 10/Mac OS X , make sure Docker Desktop is running. On Linux, Docker is available all the time once installed.

2. This pulls the image from the Docker Hub to your local machine. Now we can run a container that can take an openapi.json file and launch Swagger UI. Assuming that you have this file in the chapter1 directory, let's use the following command:

docker run --rm -p 80:8080 -e SWAGGER_JSON=/app/openapi.json -v $GOPATH/github.com/git-user/chapter1:/app swaggerapi/swagger-ui

This command tells Docker to do the following things:

• Run a container using the swaggerapi/swagger-ui image
• Mount chapter1 (where openapi.json resides) to the /app directory in the container
• Expose host port 80 to container port 8080
• Set the SWAGGER_JSON environment variable to /app/openapi.json

When the container starts, launch http://locahost in the browser. You will see nice documentation for your API:

In this way, without any cost, we can create instant documentation of our REST API using Swagger UI and Open API 3.0.

From now on, in all chapters, we will try to create Swagger files to document our API design. It is a wise decision to start API development by creating API specifications first and then jumping into implementation. I hope this chapter helped you to brush up on the basics of REST API fundamentals. In the following chapters, we will go deeply into many diverse topics.