이번에 프로젝트를 진행하면서, Spring 3.15 + Java 17 조합으로 쓰다 보니
기존에 내가 알던 Swagger 설정이 되지 않아, 여러 삽질한 끝에 방법을 찾았다.

의존성 라이브러리 추가

build.gradle에 springdoc-openapi를 추가해야 한다.

dependencies {
	[...]
	implementation 'org.springdoc:springdoc-openapi-starter-webmvc-ui:2.0.4'
    [...]
}

Yaml 설정

springdoc:
  version: '@project.version@'
  api-docs:
    path: /api-docs
  default-consumes-media-type: application/json
  default-produces-media-type: application/json
  swagger-ui:
    operations-sorter: alpha
    tags-sorter: alpha
    path: /swagger-ui.html
    disable-swagger-default-url: true
    display-query-params-without-oauth2: true
    doc-expansion: none
  paths-to-match:
    - /api/**

• version: springdoc 라이브러리의 버전을 설정한다.
  
  
• api-docs: API 문서가 제공될 경로를 /api-docs로 설정한다.
  
  
• default-consumes-media-type 및 default-produces-media-type: API에서 사용할 기본 미디어 유형을 application/json으로 설정한다.
  
  
• swagger-ui: Swagger UI의 외관 및 동작을 설정한다.
  • operations-sorter : UI에서 작업을 알파벳 순서로 정렬한다.
  • tags-sorter: Swagger : UI에서 태그를 알파벳 순서로 정렬한다.
  • path: Swagger UI에 액세스할 수 있는 경로를 /swagger-ui.html로 설정한다.
  • disable-swagger-default-url: 기본 Swagger URL을 비활성화하고 명시적인 경로 /swagger-ui.html로만 접근하도록 한다.
  • display-query-params-without-oauth2: Swagger UI에서 OAuth2 없이 쿼리 매개변수를 표시한다.
  • doc-expansion: Swagger UI에서 문서 확장을 비활성화한다.
    
    
• paths-to-match: API 문서화에 포함할 경로 패턴을 설정한다. 여기서는 /api/** 로 시작하는 모든 경로가 문서화된다.

Configuration 코드 작성

@OpenAPIDefinition(
        info = @Info(title = "투개더 API 명세서",
                description = "COMP322-team12 투개더 API 명세서",
                version = "v1"))
@RequiredArgsConstructor
@Configuration
public class SwaggerConfig {
    @Bean
    public GroupedOpenApi chatOpenApi() {
        // "/v1/**" 경로에 매칭되는 API를 그룹화하여 문서화한다.
        String[] paths = {"/v1/**"};

        return GroupedOpenApi.builder()
                .group("투개더 API v1")  // 그룹 이름을 설정한다.
                .pathsToMatch(paths)     // 그룹에 속하는 경로 패턴을 지정한다.
                .build();
    }
}

Ìnfo 내에 title, description, return하는 value에 group 매개변수는 본인의 프로젝트 관련하여 작성하면 됩니다.

@OpenAPIDefinition: OpenAPI 명세서의 기본 정보를 정의한다. 여기서는 API의 제목, 설명, 버전을 설정한다.
@RequiredArgsConstructor: Lombok 어노테이션으로, 생성자 주입을 자동으로 생성한다.
@Configuration: Spring Bean 구성 클래스임을 나타낸다.

@Bean: 스프링 Bean으로 등록될 메서드를 선언한다.

chatOpenApi 메서드: "/v1/**" 경로에 매칭되는 API를 "투개더 API v1"이라는 그룹으로 묶어서 문서화한다.
GroupedOpenApi.builder(): GroupedOpenApi를 생성하는 빌더를 시작한다.
- group("투개더 API v1"): 그룹의 이름을 설정한다.
- pathsToMatch(paths): 그룹에 속하는 경로 패턴을 설정한다.
- build(): GroupedOpenApi 객체를 빌드하여 반환한다.

Controller에 적용

@Tag(name = "User", description = "User 관련 API 입니다.")
@RestController
@RequiredArgsConstructor
@CrossOrigin
@RequestMapping("/api/user")
public class UserController {
    private final UserService userService;

    @Operation(
            summary = "회원가입",
            description = "회원가입을 합니다."
    )
    @ApiResponse(
            responseCode = "200",
            description = "회원가입에 성공하였습니다."
    )
    @PostMapping("/signup")
    public ResponseEntity<ResponseDto> signup(@RequestBody @Validated UserSignupRequest userSignupRequest) {
        try {
            userService.signup(userSignupRequest);
            return ResponseEntity.ok().body(new ResponseDto("회원가입에 성공하였습니다."));
        } catch (DuplicateEmailException e) {
            return ResponseEntity.status(HttpStatus.BAD_REQUEST).body(new ResponseDto(e.getMessage()));
        }
    }
    [...]

사진과 매칭해서 보면 어노테이션을 이해하기 쉬울 것이다.
@Tag로 설정된 name이 같은 것 끼리 하나의 api 그룹으로 묶고, 그룹에 대한 설명을 기술할 수 있다.
@Operation으로 메서드에 대한 설명을 기술할 수 있다.
@ApiResponse로 응답 결과에 따른 response 구조를 미리 확인할 수 있다.

Reference
https://springdoc.org/#migrating-from-springfox