[Spring] Swagger 3

1. Swagger 란?

Swagger 는 OAS(Open Api Specification)를 위한 프레임워크입니다.

개발자들의 필수 과제인 API 문서화를 쉽게 할 수 있도록 도와주며, 파라미터를 넣어서 실제로 어떤 응답이 오는지 테스트도 할 수 있습니다.

또한, 협업하는 클라이언트 개발자들에게도 Swagger 만 전달해주면 API Path 와 Request, Response 값 및 제약 등을 한번에 알려줄 수 있습니다.

 

2. 적용

2.1 의존성 추가

/* build.gradle */

dependencies {
    // ..
    implementation 'io.springfox:springfox-boot-starter:3.0.0'
    // ..
}

• 사용할 버전은 https://mvnrepository.com/artifact/io.springfox/springfox-boot-starter 이 곳에서 확인 가능
• Swagger 2.x 버전과 다르게 springfox-boot-starter 하위에 필요한 라이브러리를 모두 포함 합니다.
• Swagger 3.0 은 Srping Boot 2.6.x 버전에서 사용할 수 없는 이슈가 존재합니다.
  따라서 Spring Boot 의 버전을 2.5.x 로 다운그레이드 하거나 https://springdoc.org 공식문서에 있는 가이드를 참고하면 적용이 가능합니다.

2.2 Configuration

@Configuration
public class SwaggerConfig {

    @Bean
    public Docket api() {
        return new Docket(DocumentationType.OAS_30)
                .useDefaultResponseMessages(false)
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.csd.asr.intra.controller"))
                .paths(PathSelectors.any())
                .build()
                .apiInfo(apiInfo());
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("API Documentation")
                .description("API Documentation Description")
                .version("1.0")
                .build();
    }
}

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

2.3 Controller 적용

@Operation(summary = "Find User By ID", description = "Find User By ID")
@ApiResponses({
        @ApiResponse(responseCode = "200", description = "OK"),
        @ApiResponse(responseCode = "400", description = "BAD REQUEST"),
        @ApiResponse(responseCode = "404", description = "NOT FOUND"),
        @ApiResponse(responseCode = "500", description = "INTERNAL SERVER ERROR")
})
@GetMapping("/{id}")
public UserDto userById (@PathVariable(value = "id") Long id) {
    return userService.getById(id);
}

2.4 실행 후 접속

로컬 실행 후 아래의 URL 로 접속하면 된다.

• Swagger2 : http://localhost:8080/swagger-ui.html
• Swagger3 : http://localhost:8080/swagger-ui/index.html

 

3. 적용된 설정 확인

Swagger UI

 

Reference

• https://github.com/springfox/springfox
• https://springfox.github.io/springfox/docs/current/