[SpringBoot] Swagger

springdoc-openapi 와 springfox-swagger 두 종류가 있는데, 현재 2023년 3월까지도 업데이트가 되고 있는 springdoc-openapi 를 사용하기로 하자.

build.gradle

// Swagger
implementation 'org.springdoc:springdoc-openapi-starter-webmvc-ui:2.1.0'

https://springdoc.org/v2/#Introduction 를 참고해서 최신 springdoc 을 사용하자.

또한 Spring의 버전별로 경로가 달라진 점도 유의하자.
Spring 2.x.x : localhost:8080/swagger-ui.html
Spring 3.x.x : localhost:8080/swagger-ui/index.html

application.yml

springdoc:
  swagger-ui:
    path: /swagger
    use-root-path: true

Configuration

package com.board.api.config;

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()
                        .title("Board Project")
                        .version("v1.0.0"));
    }
}

사용 예시

@Tag(name = "Auth", description = "인증 관련 api")
@RestController
@RequestMapping("/auth")
@RequiredArgsConstructor
public class AuthController {
  private final AuthService authService;

  @Operation(summary = "회원가입", description = "회원가입 메서드입니다.")
  @PostMapping("/signUp")
  public SignUpRes signUp(@Validated SignUpReq signUpReq) {
    return authService.signUp(signUpReq);
  }

  ...
}

Reference
https://blog.jiniworld.me/91