본문 바로가기

리눅스

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

728x90

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 파일을 지정하십시오.

 

728x90