Swagger UI + Docker: Initial Setup

Environment

• Mac

  • CPU: Apple M1
  • OS: Sonoma 14.6.1

• Docker Desktop

  • Version: 4.34.2

Dir Structure

* Drawn by mermaid.

graph TD;
    subgraph top["top"]
        subgraph docker["docker"]
            env[".env"]
            docker_compose["docker-compose.yml"]
        end
        subgraph openapi["openapi"]
            openapi_file["openapi.yml"]
        end
    end

docker/.env

SWAGGER_UI_HOST_PORT={host-port}

docker/docker-compose.yml

services:
  swagger-ui:
    image: swaggerapi/swagger-ui:v5.17.14
    environment:
      SWAGGER_JSON: /oas/openapi.yml
    ports:
      - "${SWAGGER_UI_HOST_PORT}:8080"
    volumes:
      - ../openapi:/oas

• As image, We specify the one provided by the official.
  If the version is specified as latest, the image will be created based on the latest version.

• As environment, we specify the absolute path of the OAS file mounted inside the Docker container.
  The reason why the property name contains the string 'JSON' is that in the early days, only the .json extension was used for the file.
  Now that .yml can also be used, even if the property name does not include the string 'YAML', we can still specify the path of a .yml file there.

• As ports, we specify port 8080 mentioned in the documentation as the container port.

• As volumes, we share the OAS file between the host machine and the Docker container.
  This mapping allows the file on the host machine to be accessible inside the container.

openapi/openapi.yml

Define a minimal API documentation conforming to OAS 3.0.3.

openapi: 3.0.3
info:
  title: Sample API
  version: 1.0.0
paths:
  /hello:
    get:
      summary: Hello World Request
      responses:
        "200":
          description: OK
          content:
            text/plain:
              schema:
                type: string
                example: "Hello, World!"

Docker

Create Container and Image.

1. Open the terminal.

2. Move the current-dir to the location where docker-compose.yml is located.

3. Execute docker compose create.
   

   docker compose create
   

Open Swagger UI.

1. Start the container.
   

   docker compose start
   

2. Open http://localhost:{SWAGGER_UI_HOST_PORT}.

3. Stop the container once satisfied.
   

   docker compose stop