SpringBoot :: Swagger API 연동

dev. environment.
SpringBoot 3.1.1
Java 17

스웨거(Swagger) 란?

• 개발자가 REST API 서비스를 설계, 빌드, 문서화할 수 있도록 하는 프로젝트
• REST API를 문서화하는 도구이며, API에 대한 명세(Spec)을 관리하기 위한 프로젝트
• API가 수정되더라도 문서가 자동으로 갱신. 
• 2011 년에 처음 도입된 개념

기존, 워드나 엑셀 등 수기 작성하는 문서형 API 명세서와 달리 서버에 일정 셋팅을 해주면 API 명세서가 갱신된다.

 

백엔드 개발자의 경우 클라이언트를 개발하는 프론트엔드 개발자와 소통을 하려면 API 명세서가 꼭 필요하게 되는데

이걸 하나하나 명세하고 있는 것도 꽤나 큰 일로 파악된다.

이런 업무 로스를 줄이기 위해 서버 단에 적용하는 것이 바로바로 스웨거다.

 

API Documentation & Design Tools for Teams | Swagger

 

스웨거(Swagger)의 종류

Spring-Fox 

• 2015 년에 나온 라이브러리
• 2020년 7월 3.0.0 버전을 마지막으로 업데이트가 멈춤

Spring-Dox

• 2019년 7월에 나온 라이브러리 - SpringFox가 업데이트를 중단했던 시절..
• 2023년 4월까지 업데이트가 진행되고 있다. (23.10 기준)
• webflux라는 논 블로킹 비동기 방식의 웹 개발을 지원하도록 개발됨

고로 최신 버전의 springboot 의 경우 spring-doc을 사용하는 것이 용이하다

 

 

SpringDoc을 사용한 Swagger 적용

1. 라이브러리 추가

swagger 관련 라이브러리의 경우 버전 확인이 꼭 필요하다,

2.x.x 버전과 3.0.0버전이 swagger ui를 불러올 때 사용하는 URL이 다르기 때문.

....
      <dependency>
          <groupId>org.springframework.boot</groupId>
          <artifactId>spring-boot-starter-web</artifactId>
      </dependency>
....
      <dependency>
          <groupId>io.springfox</groupId>
          <artifactId>springfox-boot-starter</artifactId>
          <version>3.0.0</version>
      </dependency>
      <dependency>
          <groupId>io.springfox</groupId>
          <artifactId>springfox-swagger-ui</artifactId>
          <version>3.0.0</version>
      </dependency>

.....

2. 코드 작성

SwaggerConfig.java 파일과 TestController.java 파일을 생성해보자.

 

SwaggerConfig.java

package com.example.swagger.demo;


import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

/**
 * The Class SwaggerConfig.
 */
 
@Configuration
@EnableSwagger2
public class SwaggerConfig {
    @Bean
    public Docket api(){
        return new Docket(DocumentationType.SWAGGER_2)
                .select()
                .apis(RequestHandlerSelectors.any())
                .paths(PathSelectors.any())
                .build().apiInfo(apiInfo());

    }

    private ApiInfo apiInfo() {
        String description = "Welcome Log Company";
        return new ApiInfoBuilder()
                .title("SWAGGER TEST")
                .description(description)
                .version("1.0")
                .build();
    }

}

TestController.java

package com.example.swagger.demo;

import io.swagger.annotations.*;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RequestParam;
import org.springframework.web.bind.annotation.RestController;

import java.util.HashMap;
import java.util.Map;

/**
 * The Class TestController
 */
@RestController
public class TestController {

    @GetMapping(value = "/hello")
    @ApiOperation(value = "hello, world api", notes = "hellow world swagger check")
    public String hellowWorld(){
        return "hello, world";
    }


    @ApiOperation(value = "test", notes = "테스트입니다")
    @ApiResponses({
            @ApiResponse(code = 200, message = "ok"),
            @ApiResponse(code = 404, message = "page not found!")
    })
    @GetMapping(value = "/board")
    public Map<String, String> selectBoard(@ApiParam(value = "샘플번호", required = true, example = "1")
                                           @RequestParam String no) {

        Map<String, String> result = new HashMap<>();
        result.put("test title", "테스트");
        result.put("test contents", "테스트 내용");
        return  result;
    }
}

3. Swagger UI 확인

Swagger 버전에 따른 URL
2.x.x : http://localhost:8080/swagger-ui.html
2.x.x : http://localhost:8080/swagger-ui/index.html

해당 URL에 들어가게 되면.. 아래와 같이 테스트 화면이 나타나게 된다.