[Spring Boot] 스피링 부트 3.x Swagger Ui 설정

• Spring Boot 3.0.4, springdoc 2.0.4 기준
• swagger : springfox, springdoc 2가지 라이브러리가 있음. springfox 는 최근 업데이트가 없고 Spring Boot 3점 대 적용 시 일부 오류 발생 -> java 17 적용 때문인 것 같음 (Spring Boot 3 버전은 java 17 이상 필수) 그래서 springdoc 적용

1. build.gradle

• implementation 추가 implementation 'org.springframework.boot:spring-boot-starter-web' implementation 'org.springdoc:springdoc-openapi-starter-webmvc-ui:2.0.4' implementation 'org.springframework.boot:spring-boot-starter-validation'

2. application.properties

• springdoc 설정 내용 추가

#springdoc springdoc.version=v1.0.0 springdoc.swagger-ui.path=/swagger-ui.html springdoc.swagger-ui.groups-order=DESC springdoc.swagger-ui.operationsSorter=method springdoc.swagger-ui.disable-swagger-default-url=true springdoc.swagger-ui.display-request-duration=true

springdoc.api-docs.path=/api-docs springdoc.show-actuator=true springdoc.default-consumes-media-type=application/json springdoc.default-produces-media-type=application/json springdoc.paths-to-match=/**

3. SwaggerConfig.java

• swagger API 설정 : 기본 정보 설정 및 JWT 설정

import java.util.Arrays;

import org.springdoc.core.models.GroupedOpenApi;
import org.springframework.beans.factory.annotation.Value;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;

import io.swagger.v3.oas.models.Components;
import io.swagger.v3.oas.models.OpenAPI;
import io.swagger.v3.oas.models.info.Info;
import io.swagger.v3.oas.models.security.SecurityRequirement;
import io.swagger.v3.oas.models.security.SecurityScheme;

@Configuration
public class SwaggerConfig {

    @Bean
    public GroupedOpenApi manmanApi() {
        return GroupedOpenApi.builder()
            .group("manman Service API v1")
            .pathsToMatch("/**")
            .build();
    }

    @Bean
    public OpenAPI manmanOpenAPI(@Value("${springdoc.version}") String springdocVersion) {

    	Info info = new Info().title("manman Service API 명세서")
            .description("manman 프로젝트 서비스 API 명세서입니다.")
            .version(springdocVersion);

    	SecurityScheme securityScheme = new SecurityScheme()
            .type(SecurityScheme.Type.HTTP).scheme("bearer").bearerFormat("JWT")
            .in(SecurityScheme.In.HEADER).name("Authorization");

	SecurityRequirement schemaRequirement = new SecurityRequirement().addList("bearerAuth");

        return new OpenAPI()
            .components(new Components().addSecuritySchemes("bearerAuth", securityScheme))
            .security(Arrays.asList(schemaRequirement))
            .info(info);

    }

}

4. MusicController.java

• Controller 설정 : 설정한 정보가 swagger-ui.html 화면에 표현된다.

import java.util.List;

import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.http.ResponseEntity;
import org.springframework.validation.annotation.Validated;
import org.springframework.web.bind.annotation.RequestBody;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RequestMethod;
import org.springframework.web.bind.annotation.RestController;

import com.manman.common.response.ErrorResponse;
import com.manman.music.service.MusicService;
import com.manman.music.vo.MusicRequest;
import com.manman.music.vo.MusicResponse;

import io.swagger.v3.oas.annotations.Operation;
import io.swagger.v3.oas.annotations.Parameter;
import io.swagger.v3.oas.annotations.Parameters;
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;

@Tag(name = "Music", description = "Music api 입니다.")
@RestController
@RequestMapping("/music")
public class MusicController {

	final private Logger logger = LoggerFactory.getLogger(this.getClass());

	@Autowired
	private MusicService musicService;

	@Operation(summary = "Music 리스트 조회", description = "Music 리스트 정보가 조회됩니다.")
	@ApiResponses({
		@ApiResponse(responseCode = "200", description = "OK",
			content = @Content(schema = @Schema(implementation = MusicResponse.class))),
		@ApiResponse(responseCode = "400", description = "BAD REQUEST",
			content = @Content(schema = @Schema(implementation = ErrorResponse.class))),
		@ApiResponse(responseCode = "404", description = "NOT FOUND",
			content = @Content(schema = @Schema(implementation = ErrorResponse.class))),
		@ApiResponse(responseCode = "500", description = "INTERNAL SERVER ERROR",
			content = @Content(schema = @Schema(implementation = ErrorResponse.class)))
	})
	@Parameters({
		@Parameter(name = "category", description = "카테고리", example = "R01", required = true),
		@Parameter(name = "regYmd", description = "등록일시", example = "20230305", required = false)
	})
	@RequestMapping(value = "/selectMusicList", method = {RequestMethod.POST, RequestMethod.GET})
	ResponseEntity<List<MusicResponse>> selectMusicList(
		@Parameter(hidden = true) @Validated(MusicRequest.validSelectMusicList.class) @RequestBody MusicRequest musicRequest
	) throws Exception {

		logger.debug("MusicController selectMusicList musicRequest.getCategory() : " + musicRequest.getCategory());
		logger.debug("MusicController selectMusicList musicRequest.getRegYmd() : " + musicRequest.getRegYmd());

		return ResponseEntity.ok().body(musicService.selectMusicList(musicRequest));

	}

}

5. MusicRequest.java

• 요청 값 관리 Class : 요청 항목 정의 및 각 항목 별 validation 을 정의한다.

import io.swagger.v3.oas.annotations.media.Schema;
import jakarta.validation.constraints.NotBlank;
import lombok.Getter;
import lombok.Setter;

@Getter
@Setter
public class MusicRequest {

    public interface validSelectMusicList {}

    @NotBlank(groups = validSelectMusicList.class)
    @Schema(description = "카테고리")
    private String category;

    @Schema(description = "등록일시")
    private String regYmd;

    @Schema(description = "가수")
    private String artist;

    @Schema(description = "제목")
    private String title;

    @Schema(description = "등록번호")
    private String regNo;

    @Schema(description = "비디오 ID")
    private String videoId;

    @Schema(description = "썸네일")
    private String thumbnail;

}

6. MusicResponse.java

• 응답 값 관리 Class : 응답 항목을 정의한다.

import io.swagger.v3.oas.annotations.media.Schema;
import lombok.Getter;
import lombok.NoArgsConstructor;
import lombok.Setter;

@Getter
@Setter
@NoArgsConstructor
public class MusicResponse {

    @Schema(description = "등록번호")
    private String regNo;

    @Schema(description = "순위")
    private int rank;

    @Schema(description = "제목")
    private String title;

    @Schema(description = "가수")
    private String artist;

    @Schema(description = "등록일시")
    private String regYmd;

    @Schema(description = "카테고리")
    private String category;

    @Schema(description = "썸네일")
    private String thumbnail;

    @Schema(description = "비디오 ID")
    private String videoId;

}

7. swagger-ui 화면