Swagger with WebFlux - ryoobib/backend_webflux GitHub Wiki

WebFlux 프로젝트에 Swagger 적용하기

사용 이유

Swagger를 순수하게 사용해보고 싶어서 적용했다. 이전 프로젝트에서는 Rest Docs를 사용했는데, 대표적인 테스트 문서화 도구인 두 개를 모두 사용해보고 비교해보고 싶었다.

1. 의존성 추가하기


plugins {
    id 'org.springframework.boot' version '2.7.1'
    id 'io.spring.dependency-management' version '1.0.11.RELEASE'
    id "org.springdoc.openapi-gradle-plugin" version "1.3.4" // 추가
    id 'java'
}

group = 'com.example'
version = '0.0.1-SNAPSHOT'
sourceCompatibility = '11'

configurations {
    compileOnly {
        extendsFrom annotationProcessor
    }
}

repositories {
    mavenCentral()
}

dependencies {
    implementation 'org.springframework.boot:spring-boot-starter-data-mongodb-reactive'
    implementation 'org.springframework.boot:spring-boot-starter-thymeleaf'
    implementation 'org.springframework.boot:spring-boot-starter-webflux'


    implementation 'org.springdoc:springdoc-openapi-webflux-ui:1.6.9' // 추가

    compileOnly 'org.projectlombok:lombok'

    annotationProcessor 'org.projectlombok:lombok'
    testImplementation 'org.springframework.boot:spring-boot-starter-test'
    testImplementation 'io.projectreactor:reactor-test'

    annotationProcessor "org.springframework.boot:spring-boot-configuration-processor"
}

tasks.named('test') {
    useJUnitPlatform()
}

2. `application.yml` 파일 수정하기

server:
  servlet:
    context-path: /
  compression:
    enabled: true
    mime-types: text/html,text/xml,text/plain,text/css,text/javascript,application/javascript,application/json
    min-response-size: 1024
  http2:
    enabled: true
com:
  example:
    backend_webflux:
      springdoc:
        api:
          router:
            separete:
              enabled: false
            common:
              enabled: true

Router-Handler 방식으로 endpoint 인식하도록 하기 위한 설정이다.

3. Router에 Swagger 어노테이션 작성하기


@Configuration
public class UserRouter {

  @Bean
  @GetAllUserApiInfo
  public RouterFunction<ServerResponse> getAllUserRouter(UserHandler userHandler) {
    return RouterFunctions
        .route(GET("/api/user")
            , userHandler::getAllUser)
        ;
  }

  @Bean
  @GetUserByIdApiInfo
  public RouterFunction<ServerResponse> getUserRouter(UserHandler userHandler) {
    return RouterFunctions
        .route(GET("/api/user/{id}")
            , userHandler::getUser);
  }

  @Bean
  @CreateUserApiInfo
  public RouterFunction<ServerResponse> createUserRouter(UserHandler userHandler) {
    return RouterFunctions
        .route(POST("api/user")
            , userHandler::createUser);
  }

  @Bean
  @ModifyUserByIdApiInfo
  public RouterFunction<ServerResponse> modifyUserRouter(UserHandler userHandler) {
    return RouterFunctions
        .route(PUT("api/user/{id}")
            , userHandler::modifyUser);
  }

  @Bean
  @DeleteUserByIdApiInfo
  public RouterFunction<ServerResponse> deleteUserRouter(UserHandler userHandler) {
    return RouterFunctions
        .route(DELETE("api/user/{id}")
            , userHandler::deleteUser);
  }

}

기존의 Chaining 방식에서 Separate 방식으로 변경하였다. 개별 Router 마다 Swagger API Info를 어노테이션으로 적용하기 위함이다.

4. Swagger API Info 어노테이션 작성하기

@Retention(RetentionPolicy.RUNTIME)
@Target({ElementType.METHOD, ElementType.TYPE})
@RouterOperations({
    @RouterOperation(
        method = RequestMethod.GET,
        operation =
        @Operation(
            description = "Get all users ",
            operationId = "getAllUser",
            tags = "users",
            responses = {
                @ApiResponse(
                    responseCode = "200",
                    description = "Get all users endpoint",
                    content = {
                        @Content(
                            mediaType = MediaType.APPLICATION_JSON_VALUE,
                            array = @ArraySchema(schema = @Schema(implementation = User.class)))
                    }),
                @ApiResponse(
                    responseCode = "400",
                    description = "Not found response",
                    content = {
                        @Content(
                            mediaType = MediaType.APPLICATION_JSON_VALUE,
                            schema = @Schema(implementation = ExceptionResponse.class))
                    })
            }))
})
public @interface GetAllUserApiInfo {

}

Swagger-ui에서 보고 싶은 정보를 작성하면 된다.

아래 블로그를 참고하였다.

https://medium.com/dandelion-tutorials/documenting-functional-rest-endpoints-with-springdoc-openapi-21657c0ebc8a

Swagger 적용 후 느낀 점

Swagger를 이용하면 Router 클래스에 직접적인 코드 작성으로 가독성을 해친다는 점을 여러 블로그를 통해 본 적이 있다. 이는 어노테이션을 이용해 따로 분리로 가독성을 확보할 수 있다는 점에서 크게 공감하지 못하였다. Rest Docs와 다르게 테스트 코드를 작성하지 않아도 된다는 점에서 일감이 줄었다고 느낄 수는 있으나 어노테이션을 커스터마이징 하면서 작성하는 코드의 수도 만만치 않기 때문에 크게 두 도구 모두 코드 작성의 양으로 비교하는 것은 바람직하지 않을 거 같다.

혼자 개발을 하다 보니, 다른 사람과 문서 공유를 할 일이 없어서 swagger의 장점을 최대로 느껴 보지는 못했다. 그러나 적용이 쉽고, 설정이 많지 않은 점에서는 매력적이었다.