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