[Spring] Spring 3.x Swagger 적용

Spring 3.x에서 Swagger를 적용해보자.

기존에는 Spring 2.x에서 swaggerfox를 가져와 API를 문서화 했다.
Spring 3.x에서는 swaggerfox가 아닌 swaggerdoc을 권장한다고 한다.

실제로 각각의 깃허브를 살펴보면 swaggerfox의 마지막 커밋이 2020년인 반면에
swaggerdoc은 2023년인 것으로 보아 Spring의 버전에 맞춰
업데이트 되는 것을 확인 할 수 있다.

환경

JDK 21
Spring 3.2.1
Gradle Kotlin

의존성

implementation("org.springdoc:springdoc-openapi-starter-webmvc-ui:2.0.2")

여기까지만 셋팅해도 서버를 가동시켜보면 정상적으로 서버가 올라가는걸 알 수 있는데,
바로 http://localhost:8081/swagger-ui/index.html 로 접근해보면 API 문서가 나온다.

swaggerfox의 url은 http://localhost:8081/swagger-ui.html 인 반면
swaggerdoc의 url은 http://localhost:8081/swagger-ui/index.html 로
서로 다르다.

swagger 설정

swaggerfox와 같이 추가적인 설정이 가능하다.
아래와 같이 OpenApi를 Bean으로 등록해서 정보를 입력 할 수 있다.

SwaggerConfig.java

import io.swagger.v3.oas.annotations.OpenAPIDefinition;
import io.swagger.v3.oas.models.OpenAPI;
import io.swagger.v3.oas.models.info.Info;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;

@Configuration
public class SwaggerConfig {

    @Bean
    public OpenAPI openApi() {
        return new OpenAPI()
                    .info(new Info()
                            .version("v0.1")
                            .title("프로젝트 이름")
                            .description("API DOC")
                    );
    }

}

Controller 설정

아래와 같이 controller에 어노테이션을 추가하여 API 문서에 추가적인 정보를 그려줄 수 있다.

package com.cox.seulha.controller;

import com.cox.seulha.dto.User;
import io.swagger.v3.oas.annotations.Operation;
import io.swagger.v3.oas.annotations.media.Content;
import io.swagger.v3.oas.annotations.media.Schema;
import io.swagger.v3.oas.annotations.responses.ApiResponse;
import io.swagger.v3.oas.annotations.responses.ApiResponses;
import io.swagger.v3.oas.annotations.tags.Tag;
import org.springframework.http.ResponseEntity;
import org.springframework.stereotype.Controller;
import org.springframework.web.bind.annotation.GetMapping;

@Tag(name = "데모", description = "데모 api")
@Controller
public class TestController {

    @Operation(summary = "User 조회", description = "User 조회 API")
    @ApiResponses(value = {
            @ApiResponse(responseCode = "200", description = "조회 성공", content = @Content(schema = @Schema(implementation = User.class))),
            @ApiResponse(responseCode = "400", description = "Bad Request", content = @Content(schema = @Schema(implementation = Error.class)))
    })
    @GetMapping(value = "/test")
    public ResponseEntity<User> test() {
        return ResponseEntity.ok(new User());
    }

}

swaggerfox에도 있었나 ?
기억이 안 나는데 swaggerdoc에서는 @ApiResponse가 받는 속성이 좀 눈에 띈다.

responseCode는 물론 content를 전달 받는데,
responseCode에 따라 데이터가 리턴되는 형식을 보여줄 수 있다.

여기서 @Content가 받는 schema에 클래스의 정보를 전달해주면
아래 사진과 같이 Schemas에 위에서 전달해준 객체의 정보가 그려진다.

객체 설정

객체 설정은 @Schema로 다 처리할 수 있다.

User.java

import io.swagger.v3.oas.annotations.media.Schema;
import lombok.Data;

@Data
@Schema(description = "TEST USER")
public class User {

    @Schema(description = "USER ID", nullable = false, example = "testtest", maxLength = 20, minLength = 8)
    private String userId;

    @Schema(description = "USER PASSWORD", nullable = false, example = "testPw123", maxLength = 14, minLength = 8)
    private String userPw;

    @Schema(description = "USER NAME", nullable = false, example = "홍길동", maxLength = 5, minLength = 2, defaultValue = "홍길동")
    private String userNm;

    @Schema(description = "탈퇴 여부", nullable = true, example = "N", maxLength = 1, defaultValue = "N", allowableValues = {"Y", "N"})
    private String dropYn;

}

요청해보면 설정에 맞춰 swagger가 벨리데이션 체크를 해준다.