Hello World 처럼: Swagger 설치 및 설정 기초

Swagger 설치 및 설정 기초

1. 소개

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

2. REST API 서버

Swagger Tool로 테스트하고자 하는 API 서버를 실행합니다. API 서버의 URL이 다음과 같다고 가정합니다.
- URL: http://{server-addr}:8080/api

3. Swagger Editor

3.1. Swagger Editor 다운로드

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

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

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

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

Node.js를 설치합니다.

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

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

브라우져에서 http://localhost:8061 주소를 엽니다.
이전에 작성해 두었던 API 정의 파일이 있으면 File -> Import file 메뉴를 통해서 불러 옵니다.

3.4. 도커로 띄우기

3.4.1. 설치 및 실행

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

sudo docker pull swaggerapi/swagger-editor

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

# 백그라운드 모드로 도커 이미지 실행 
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

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

3.4.2. 도커 이미지 종료

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

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

도커 컨테이너를 종료합니다.
```
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 문제인지 확인하는 방법

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

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

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

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

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

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

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

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

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

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();  
    }  
}

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. 설치 및 실행