[SpringBoot] Swagger API 문서 자동화 간단 연동, 테스트하기(1)

Swagger-ui 를 활용한 문서 자동화 

- 개발한 Rest API 들의 목록을 확인하고 테스트 할 수있는 Swagger-UI를 Spring Boot 프로젝트에 연동(설정)하고 

   사용 하는 방법을 알아보자. 

 

 

Spring Boot 3.x^ 버전에서의 적용 방법은 아래 링크를 참고하세요

https://lucas-owner.tistory.com/80

[Spring boot] Spring Boot 3.x^ - Swagger 적용(2)

 

 

 

○ Swagger란 ?

• Swagger는 개발한 Rest API를 문서화 한다.
• 문서화된 내용을 통해 관리 & API 호출을 통한 테스트를 가능케 한다. 
• API Test 할때 많이 사용되는 PostMan과 비슷하다. 

▶ Swagger 라이브러리의 종류 2가지

Swagger는 2가지 종류의 라이브러리가 존재한다.

Spring-fox, Spring-Doc 2가지가 존재하며 해당 글에서는 Spring-fox를 연동해본다.

• Spring-Fox
  • 오래전에 나온 라이브러리 이다.
  • 2020년 이후로 업데이트가 없다.
• Spring-Doc
  • 2019년에 나온 라이브러리 이다.
  • 꾸준하게 업데이트가 되고 있다. 

---

목차

1. Swagger 설정 
   1. 의존성 추가 
   2. 설정 파일 생성
2. Swagger UI 연동 확인 & 설명
3. API Test 방법
   1. Post
   2. Get

---

Spring Boot : 2.7.6 ver

Swagger-fox : 2.9.2 

Gradle 

---

Swagger 설정 & 프로젝트 적용

 

Swagger 설정 하기

 

1. 의존성 추가 (Gradle)

- build.gradle 디펜던시에 아래의 의존성을 추가한다.

implementation group: 'io.springfox', name: 'springfox-swagger-ui', version: '2.9.2' // swagger
implementation group: 'io.springfox', name: 'springfox-swagger2', version: '2.9.2' //swagger

 

2. Swagger 설정 파일 생성.

- SwaggerConfig.java 파일 생성 후 설정

 

- SwaggerConfig.class 

@Configuration
@EnableWebMvc
@EnableSwagger2
public class SwaggerConfig implements WebMvcConfigurer {

    /*
    Docket: Swagger 설정의 핵심이 되는 Bean
    useDefaultResponseMessages: Swagger 에서 제공해주는 기본 응답 코드 (200, 401, 403, 404). false 로 설정하면 기본 응답 코드를 노출하지 않음
    apis: api 스펙이 작성되어 있는 패키지 (Controller) 를 지정
    paths: apis 에 있는 API 중 특정 path 를 선택
    apiInfo:Swagger UI 로 노출할 정보
    */

    private static final String SERVICE_NAME = "Make Project";
    private static final String API_VERSION = "V1";
    private static final String API_DESCRIPTION = "MakeProject API TEST";
    private static final String API_URL = "http://localhost:8080/";

    @Bean
    public Docket api() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.any()) // RequestMapping의 모든 URL LIST
                .paths(PathSelectors.any()) // .any() -> ant(/api/**") /api/**인 URL만 표시
                .build();
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder().title(SERVICE_NAME) // 서비스명
                .version(API_VERSION)                   // API 버전
                .description(API_DESCRIPTION)           // API 설명
                .termsOfServiceUrl(API_URL)             // 서비스 url
                .licenseUrl("라이센스 표시할 url")
                .build();

    }// API INFO
    
    // 아래 부분은 WebMvcConfigure 를 상속받아서 설정하는 Mehtod 
    @Override
    public void addResourceHandlers(ResourceHandlerRegistry registry) {
        registry.addResourceHandler("/swagger-ui.html")
                .addResourceLocations("classpath:/META-INF/resources/");

        registry.addResourceHandler("/webjars/**")
                .addResourceLocations("classpath:/META-INF/resources/webjars/");
        // -- Static resources
        registry.addResourceHandler("/static/**").addResourceLocations("classpath:/static/");

    }
}

 

- 다른 Swagger Config 와 다르게 복잡해 보이지만 코드를 보면 단순하게 

  Swagger-UI에 표시하고 싶은 내용들을 설정 해준것이다. 

 

- Method 명이 이해하기 쉽게 표기 되어 있어서 보는데 큰 문제는 없을것이다.

- 에러 핸들링에 대한 내용이라던지, url 설정 등 상세 설정은 더욱 많다, 라이브러리를 확인 해보는것도 좋은 방법이다.

---

3. Swagger-ui 확인 및 설명 

 

- 서버 기동 후 브라우저에 접속하여

   http://localhost:8080/swagger-ui.html/ 해당 주소로 이동. 

   현재 Rest API 목록이 있다면 아래와같이 표시 될것이다.

 

- 현재 Request Mapping 의 모든 url List 를 지정 했기 때문에. Controller 가 전부 나온것을 확인 가능하다.

- API 문서 이름, 설정 정보 등등 Swagger 상세 설정한 내용도 변경되어 표시된다. (Default: Api Documentaion ~ 으로 표시됨)

---

3-1 List 를 펼쳐 보자 

- 아래와 같이 해당 컨트롤러 내부에 존재하는 API 목록이 나오게 된다. 

- 위의 자세한 기능 사용법은 아래에서 다루도록 하겠다! 

---

3-2 API를 확인하기 쉽게 설명을 달아보자

- 많은 사람들은 여기까지만 설정하고 사용하는 경우가 있다.

하지만 실무나 개인 프로젝트에서 Controller, API의 갯수가 많아진다면 ??

 

협업을 진행하게 된다면 다른 사람이 Test 를 진행 하게 된다면

해당 API는 무엇인지, 어떤걸 사용해야 하는지 파악하기 어려울 것이다.

API 문서화를 좀더 체계적으로 하기 위해 설명을 추가해보자.

 

Controller 이동 후 각 Method 위에 @ApiOperation(option) 설정을 해주자.

- import io.swagger.annotations.ApiOperation; // Swagger 제공

- 설정 후 서버 재기동 및 Swagger UI 이동

- ApiOperation 에 적용한 설명이 표시되는것을 확인 가능하다.

 

---

4. API 테스트를 진행해 보자

 

4-1 Post 기능을 사용해 보자. 

- 버전에 따라 상이 할 수 있지만 대게 비슷하다.

- 여기서는 DTO 타입으로 @RequestBody 를 받기 때문에 

  요청 할 샘플 Body 가 제공되는 것을 확인 할 수 있다. 

  (Spring-Fox = Description  Spring-Docs Model Schma 로 표시)

 

*만약 파라미터를 작성하는 부분이 보이지 않는다면! Try it out 버튼을 클릭하자! 

 

- Save(저장) API 를 테스트 해보자.

- 아래와 같이 테스트 파라미터 작성 후 Execute 버튼 클릭.

- post API 는 Body 로 받기 때문에 JSON 형식으로 작성 해주자.(샘플 텍스트가 생성되니 참고하자)

 

* Swagger는 해당 메소드가 받는 파라미터, 어떤 형태인지 표시 해주니 확인을 잘하자!

 

- 결과 확인

 

- 무언가 굉장히 많은 내용이 출력되지만 지금 상황에서는 아래의 빨간 네모 박스를 확인 하면 된다.

• Return 타입을 Save 한 내용으로 코드를 만들었다면.
• Response body에 결과가 출력 된다.
• Response Status 에 서버와 통신한 상태 값을  표시해준다. 

---

4-2 저장한 내용을 DB에서 가져와 보자 (Get)

- 미리 만들어 둔 조회 API 를 통해서 DB 데이터를 확인 해보자.

 

- 방금전 Post 한 Data 가 DB에 정상적으로 Save 되었고.

- 출력 또한 정상적으로 되는것을 확인 할 수 있다. 

 

---

정리

협업을 하는 프로젝트 라면 (토이, 실무) 테스트 진행시

어디에 어떤 API 가 있는지, 어떻게 사용해야 하는지 수고스러운 작업을 반복하게 되는데

Swagger-ui 를 통해 API 문서화가 이루어지고 관리를 하게 된다면, 불필요한 작업을 진행하지 않아도 되는점이 편리한것 같다.

 

필자는 실무에서 먼저 사용해보고 편리함을 느낀 후로 

개인 프로젝트에서는 좀더 신경써서 Swagger를 관리하여 체계적인 작업을 진행 하려 노력한다. 

 

(또한 API 개발 완료 후 해당 문서를 작성할 때...... Swagger를 사용하여 문서 작성 시간을 줄였다... API Test 보다 제일 좋은점이라고 생각한다. )