Spring Boot 3.0 버전업 Swagger 변경 사항 정리

Swagger

개발한 REST API 를 문서화해주는 도구로, 사용자가 편리하게 API 테스트할 수 있는 기능

 

사용 방법

• Spring Boot 3.0 이하 버전

build.gradle dependencies 에서 springfox-boot-starter 추가하여 사용

implementation 'io.springfox:springfox-boot-starter:3.0.0'

• Spring Boot 3.0 이상 버전

Spring Boot 3.x 이상 부터는 springfox가 아닌 springdoc을 사용

implementation 'org.springdoc:springdoc-openapi-starter-webmvc-ui:2.0.2'

 

Annotations

Swagger2 (Springfox)	Swagger3 (Springdoc)
@Api	@Tag
@ApiIgnore	@Parameter(hidden=true) @Operation(hidden=true) @Hidden
@ApiImplicitParam	@Parameter
@ApiImplicitParams	@Parameters
@ApiModel	@Schema
@ApiModelProperty(hidden = true)	@Schema(accessMode = READ_ONLY)
@ApiOperation(value = "생성", notes = "데이터 생성", nickname="CreateData")	@Operation(summary = "생성", description = "데이터 생성", operationId="CreateData")
@ApiParam(allowableValues="Y,N")	@Parameter(schema = @Schema(type = "string", allowableValues = {"Y", "N"})
@ApiResponse(code = 200, message = "OK")	@ApiResponse(responseCode = "200", description = "OK")

 

 

사용 예시

config 설정

@Configuration
public class OpenApiConfig {

    @Bean
    public OpenAPI openAPI(@Value("${springdoc.version}") String springDocVersion) {
        Info info = new Info()
                .title("Swagger API Test")
                .version(springDocVersion)
                .description("Swagger API 테스트 입니다.")
                .contact(new Contact().name("haenny").email("haenny@tistory.com").url("https://haenny.tistory.com"));

        return new OpenAPI()
                .components(new Components())
                .info(info);
    }
}

 

Controller

@Tag(name = "Main API Controller", description = "API 정보를 제공하는 메인 컨트롤러")
@RestController
@RequestMapping("/main")
public class MainController {
	...
}

 

Method

@GetMapping("/users/{userId}")
@Operation(operationId = "DetailUser", summary = "사용자 상세 조회", description = "사용자를 상세 조회한다.")
@ApiResponses(value = {
	@ApiResponse(responseCode = "200", description = "OK", content = @Content(schema = @Schema(implementation = int.class))),
	@ApiResponse(responseCode = "404", description = "User Not Found", content = @Content(schema = @Schema(implementation = int.class)))
})
public int detailUser(@PathVariable @Parameter(name = "userId", description = "사용자ID", in = ParameterIn.PATH, example = "10") int userId,
		      @RequestParam @Parameter(name = "userName", description = "사용자명", in = ParameterIn.QUERY, example = "해니") int userName) {
		// ...        
}

 

DTO

@Getter
@Setter
public class UserRequest {

	@Schema(description = "이름", defaultValue = "haenny", requiredMode = Schema.RequiredMode.REQUIRED, example = "haenny")
	private String name;
    
	@Schema(description = "나이", defaultValue = "10", requiredMode = Schema.RequiredMode.REQUIRED, example = "30")
	private int age;
}