Swagger 설치 및 설정 기초

1. 소개

• OpenAPI Specification - REST API를 정의하는 형식에 대한 규격이며 이전에는 Swagger Specification이라고 하였습니다.
• Swagger Tool - OpenAPI를 정의할 수 있는 편집기, API를 테스트할 수 있는 UI 등을 포함하고 있습니다.

2. REST API 서버

1. Swagger Tool로 테스트하고자 하는 API 서버를 실행합니다. API 서버의 URL이 다음과 같다고 가정합니다.

   • URL: http://{server-addr}:8080/api

3. Swagger Editor

3.1. Swagger Editor 다운로드

1. GitHub에서 다운로드합니다.
2. 다운로드한 파일의 압축을 풉니다. 이후부터 압축을 푼 폴더를 {editor-dir}로 표기합니다.

3.2. 브라우져에서 직접 열기

1. 브라우져에서 {editor-dir}/index.html 파일을 엽니다.
2. 이전에 작성해 두었던 API 정의 파일이 있으면 File -> Import file 메뉴를 통해서 불러 옵니다.

3.3. Node.js를 사용하여 서버로 띄우기

1. Node.js를 설치합니다.

2. http-server 모듈을 설치하고 시작합니다.

   npm install -g http-server
   http-server -p 8061 {editor-dir}
   

3. 브라우져에서 http://localhost:8061 주소를 엽니다.

4. 이전에 작성해 두었던 API 정의 파일이 있으면 File -> Import file 메뉴를 통해서 불러 옵니다.

3.4. 도커로 띄우기

3.4.1. 설치 및 실행

1. 도커 이미지를 설치합니다.

   sudo docker pull swaggerapi/swagger-editor
   

2. 도커 이미지를 실행합니다.

   # 백그라운드 모드로 도커 이미지 실행 
   sudo docker run -d -p 8061:8080 -e BASE_URL=/swagger-editor -e SWAGGER_JSON=/mnt/api.yaml -v /home/test:/mnt swaggerapi/swagger-editor
   

3. 브라우져에서 http://localhost:8061/swagger-editor 주소를 엽니다.

3.4.2. 도커 이미지 종료

1. 도커 컨테이너 목록을 표시합니다.

   sudo docker container ls
   CONTAINER ID        IMAGE                   COMMAND                  CREATED             STATUS              PORTS                          NAMES
   a0242be185b4        swaggerapi/swagger-ui   "/docker-entrypoin..."   6 seconds ago       Up 5 seconds        80/tcp, 0.0.0.0:80->8080/tcp   gifted_payne
   

2. 도커 컨테이너를 종료합니다.

   sudo docker stop gifted_payne
   

3.5. CORS 문제 해결

3.5.1. 문제 증상

Swagger Editor나 Swagger UI에서 API를 테스트했을 때 Swagger 도구에서 아래와 같은 오류 메시지를 표시하는 경우가 있습니다.

Failed to fetch.
Possible Reasons:
* CORS
* Network Failure
* URL scheme must be “http” or “https” for CORS request.

3.5.2. CORS 문제인지 확인하는 방법

크롬 브라우져를 사용하는 경우에 대하여 설명합니다.

1. 브라우져의 도구 더보기 - 개발자 도구 메뉴를 클릭합니다.
2. 개발자 도구 창에서 Console 탭을 클릭합니다.
3. 오류 로그에 blocked by CORS policy 문구가 포함되어 있으면 CORS 문제입니다.

3.5.3. 문제의 원인 및 해결 방법

Swagger 서버 주소와 API 서버 주소간 다음 세 가지 중 하나라도 다르면 CORS 문제가 발생할 수 있습니다.

• URL 스킴(“http”, “https”)
• 도메인
• 포트

브라우져는 JavaScript를 다운받은 서버 주소(여기서는 Swagger 서버)와 JavaScript가 XMLHttpRequest를 사용하여 연결하고자 하는 서버(여기서는 API 서버) 주소가 서로 다를 때 연결하고자 하는 서버가 CORS를 지원하는지 검사합니다. 이 검사를 통과하지 못하면 브라우져는 CORS 오류 메시지를 출력하고 API 호출을 중단합니다.

이 문제를 해결하는 방법으로 여러 가지가 있습니다.

1. Swagger 서버와 API 서버를 동일한 주소로 서비스
2. API 서버가 CORS를 지원하도록 구성
3. Swagger Hub 이용
4. 브라우져의 CORS 검사 기능을 비활성화 (보안 우려로 비추천)

여기서는 두 번째 방법으로 문제를 해결하고자 하며 다음은 API 서버가 Spring Boot를 사용하는 경우에 대한 해결 방법입니다.

1. HttpSecurity의 cors()를 호출합니다.

   @Configuration  
   @EnableWebSecurity  
   @EnableGlobalMethodSecurity(securedEnabled = true, prePostEnabled = true)  
   public class SecurityConfig extends WebSecurityConfigurerAdapter {  
       @Override  
       public void configure(HttpSecurity http) throws Exception {  
           http.sessionManagement().sessionCreationPolicy(SessionCreationPolicy.IF_REQUIRED);  
           http.authorizeRequests().anyRequest().permitAll();  
           http.csrf().disable();  
           http.headers().frameOptions().disable();  
           http.cors();  
       }  
   }
   

2. CorsRegistry와 CorsRegistration을 설정합니다.

   @EnableWebMvc  
   @Configuration  
   public class WebMvcConfig implements WebMvcConfigurer {
       @Override  
       public void addCorsMappings(CorsRegistry registry) {  
           CorsRegistration registration = registry.addMapping("/**");  
           registration.allowedMethods("DELETE", "GET", "HEAD", "OPTIONS", "POST", "PUT");
       }
   }
   

3.6. API 정의를 파일로 저장하기

• File -> Save as YAML 메뉴를 클릭하고 api.yaml과 같은 이름을 지정하여 파일로 저장합니다.

4. Swagger UI

4.1. api.yaml 파일 준비

4.1.1. API 서버 주소 지정

servers:
- url: http://{server-addr}:8080/api

4.2. 도커로 띄우기

4.2.1. 설치 및 실행

1. 도커 이미지를 설치합니다.

   # yum 최신 업데이트
   sudo yum update
   
   # docker 설치 및 시작
   sudo yum install docker
   sudo systemctl start docker
   
   # swagger-ui docker 이미지 pull 
   sudo docker pull swaggerapi/swagger-ui
   

2. 도커 이미지를 실행합니다.

   # 백그라운드 모드로 도커 이미지 실행
   sudo docker run -d -p 8060:8080 -e BASE_URL=/swagger-ui -e SWAGGER_JSON=/mnt/api.yaml -v /home/test:/mnt swaggerapi/swagger-ui
   

3. 브라우져에서 http://localhost:8060/swagger-ui 주소를 엽니다.

4.2.2. 도커 이미지 종료

1. 도커 컨테이너 목록을 표시합니다.

   sudo docker container ls
   CONTAINER ID        IMAGE                   COMMAND                  CREATED             STATUS              PORTS                          NAMES
   a0242be185b4        swaggerapi/swagger-ui   "/docker-entrypoin..."   6 seconds ago       Up 5 seconds        80/tcp, 0.0.0.0:80->8080/tcp   gifted_payne
   

2. 도커 컨테이너를 종료합니다.

   sudo docker stop gifted_payne
   

참고 자료

OpenAPI

• What Is OpenAPI?
• Swagger Editor Documentation

CORS 지원

• Swagger CORS
• CORS with Spring

Written with StackEdit.