Docker를 사용하여 Swagger UI를 실행하고 REST API를 테스트하는 방법

Docker를 사용하여 Swagger UI를 실행하고 REST API를 테스트하는 방법

Swagger UI를 Docker 컨테이너로 실행하면 로컬 환경에서 간편하게 API 테스트를 수행할 수 있습니다.

1. Docker 설치

Docker를 시스템에 설치합니다. Docker 공식 웹사이트에서 각 운영체제에 맞는 설치 방법을 확인할 수 있습니다.

2. Swagger JSON 파일(API 스펙 정의)

Swagger JSON 파일(swagger.json)은 API의 스펙을 정의하는 파일입니다.

이 파일에는 API의 엔드포인트, 매개변수, 응답 형식, 보안 설정 등이 기술되어 있습니다.

vim swagger.json

{
  "openapi": "3.0.0",
  "info": {
    "title": "Sample API",
    "version": "1.0.0"
  },
  "paths": {
    "/users": {
      "get": {
        "summary": "Get a list of users",
        "responses": {
          "200": {
            "description": "Successful response",
            "content": {
              "application/json": {
                "example": {
                  "users": [
                    { "id": 1, "name": "Alice" },
                    { "id": 2, "name": "Bob" }
                  ]
                }
              }
            }
          }
        }
      }
    }
  }
}

• openapi: 사용하는 OpenAPI Specification의 버전을 명시합니다.
• info: API의 기본 정보를 나타냅니다.
• paths: API의 엔드포인트와 해당하는 HTTP 메서드별로 정의합니다. 위 예시에서 /users 엔드포인트의 GET 메서드를 정의하였습니다.
• summary: 해당 엔드포인트의 요약 설명을 나타냅니다.
• responses: 응답 형식을 정의합니다. 위 예시에서는 200 응답에 대한 설명과 예시를 정의하였습니다.

이 외에도 Swagger JSON 파일은 매개변수, 보안 정책, 데이터 모델 등에 대한 정보를 담을 수 있습니다.

728x90

3. Swagger UI Docker 이미지 실행

터미널을 열고 아래 명령어를 실행하여 Swagger UI Docker 이미지를 실행합니다.

docker run -p 8080:8080 -e SWAGGER_JSON=/app/swagger.json -v ./swagger.json:/app/swagger.json swaggerapi/swagger-ui

Unable to find image 'swaggerapi/swagger-ui:latest' locally
latest: Pulling from swaggerapi/swagger-ui
4060ece20d7a: Pull complete
7875cf511d73: Pull complete
f0fedff218af: Pull complete
7a5666f74111: Pull complete
0632371cce84: Pull complete
3d333a45c7c7: Pull complete
6de0e7ce1b7e: Pull complete
6d91d070ecef: Pull complete
8997c1960314: Pull complete
8a6209e00284: Pull complete
c1863f8ed1f2: Pull complete
39620f6807e2: Pull complete
10b33fd4e75c: Pull complete
b61140bad1ca: Pull complete
Digest: sha256:c5cbd527b8e197a12dbd51428b4499f1d3d1276b69da39c8b178ee31a3cc95e4
Status: Downloaded newer image for swaggerapi/swagger-ui:latest
/docker-entrypoint.sh: /docker-entrypoint.d/ is not empty, will attempt to perform configuration
/docker-entrypoint.sh: Looking for shell scripts in /docker-entrypoint.d/
/docker-entrypoint.sh: Launching /docker-entrypoint.d/10-listen-on-ipv6-by-default.sh
10-listen-on-ipv6-by-default.sh: info: Getting the checksum of /etc/nginx/conf.d/default.conf
10-listen-on-ipv6-by-default.sh: info: Enabled listen on IPv6 in /etc/nginx/conf.d/default.conf
/docker-entrypoint.sh: Sourcing /docker-entrypoint.d/15-local-resolvers.envsh
/docker-entrypoint.sh: Launching /docker-entrypoint.d/20-envsubst-on-templates.sh
20-envsubst-on-templates.sh: Running envsubst on /etc/nginx/templates/default.conf.template to /etc/nginx/conf.d/default.conf
/docker-entrypoint.sh: Launching /docker-entrypoint.d/30-tune-worker-processes.sh
/docker-entrypoint.sh: Launching /docker-entrypoint.d/40-swagger-ui.sh
/docker-entrypoint.sh: Configuration complete; ready for start up
2023/08/26 08:23:57 [notice] 1#1: using the "epoll" event method
2023/08/26 08:23:57 [notice] 1#1: nginx/1.25.1
2023/08/26 08:23:57 [notice] 1#1: built by gcc 12.2.1 20220924 (Alpine 12.2.1_git20220924-r4)
2023/08/26 08:23:57 [notice] 1#1: OS: Linux 5.15.49-linuxkit-pr
2023/08/26 08:23:57 [notice] 1#1: getrlimit(RLIMIT_NOFILE): 1048576:1048576
2023/08/26 08:23:57 [notice] 1#1: start worker processes
2023/08/26 08:23:57 [notice] 1#1: start worker process 62
2023/08/26 08:23:57 [notice] 1#1: start worker process 63
2023/08/26 08:23:57 [notice] 1#1: start worker process 64
2023/08/26 08:23:57 [notice] 1#1: start worker process 65
2023/08/26 08:23:57 [notice] 1#1: start worker process 66

• -p 8080:8080: 호스트의 8080 포트와 컨테이너의 8080 포트를 매핑합니다.
• -e SWAGGER_JSON=/app/swagger.json: Swagger UI에 표시할 Swagger JSON 파일의 경로를 설정합니다. /app/swagger.json은 컨테이너 내부 경로입니다.
• -v ./swagger.json:/app/swagger.json: 호스트 머신에 있는 Swagger JSON 파일을 컨테이너 내부의 /app/swagger.json 경로로 마운트합니다.

4. Swagger UI 접속

웹 브라우저에서 http://localhost:8080을 열어 Swagger UI에 접속합니다. 여기서 API 문서를 시각적으로 볼 수 있으며, 테스트 요청을 보내고 응답을 확인할 수 있습니다.

s1

 

이제 이 방법으로 Swagger UI를 Docker 컨테이너로 실행하고 REST API를 테스트할 수 있습니다. 만약 다른 Swagger JSON 파일을 사용하고 싶다면 -e SWAGGER_JSON과 -v 옵션을 조정하여 사용하고자 하는 Swagger 파일을 지정하십시오.