혼자서 개발새발

Springdoc ) Spring Boot 3 이상에서는 Swagger2 대신 Springdoc(Swagger3)

휴일이 2024. 1. 5. 23:04

 

 

자동으로 API 명세서를 생성해주는 Swagger 라는 좋은 녀석이 있다고 했다.

사용해보려고 직접 종속성도 추가해보았으나

Swagger 는 Spring boot 3 버전 이상을 지원하지 않는다고 한다 ㅡ.ㅡ

(javax 클래스 못찾겠다고 오류뜸;; spring boot 3 부터는 jakarta 쓴다궁...)

 

그래서 Swagger2 대신 스프링 부트 3 부터는 springdoc 을 이용한대잉~

이건 Swagger3 라고 한다요

안 사용해볼 수 없지!

 

 

 

Gradle

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

 

난 Gradle 을 사용하기 때문에 요렇게 종속성을 추가해주었다.

 

 

 

application.yml

springdoc:
  packages-to-scan: com.account.yomankum
  default-consumes-media-type: application/json;charset=UTF-8
  default-produces-media-type: application/json;charset=UTF-8
  swagger-ui:
    path: /yomankum/api-docs
    disable-swagger-default-url: true
    display-request-duration: true
    operations-sorter: method

 

application.yml 에 간단한 springdoc 설정을 해준다.

API doc 을 만들, 스캔할 패키지를 설정하고

주고 받을 MediaType 설정!

사실 기본이 application/json 이긴 함ㅋ

swagger default url 은 활성화하고

millisecond 단위 표시도 활성화해줌~

정렬도 순서도 설정할 수 있는데 나는 HTTP 메서드 순서로 정렬함 ㅎ_ㅎ

 

 

 

Controller

@Slf4j
@RestController
@RequiredArgsConstructor
@RequestMapping("/login")
@Tag(name = "LOGIN", description = "로그인 페이지 API 명세서")
public class LoginController {

    private final UserService userService;

    @PostMapping
    @Operation(summary = "일반 회원 로그인", description = "일반 회원용 로그인")
    public ResponseEntity<Response> login(@RequestBody @Valid LoginDto loginDto) {

        Map<String, String> tokens = null;
        try {
            tokens = userService.login(loginDto);
        } catch (IllegalArgumentException e) {
            e.printStackTrace();
            return Response.badRequest(ResponseCode.LOGIN004);
        }

        return Response.ok(ResponseCode.LOGIN000, tokens);
    }
}

 

 

해당 애노테이션들은

기존 Swagger2 에서 이름이 초끔씩 변경되었다

 

 

springdoc 공식 document 에 들어가면 확인 가능 ^0^/)

 

 

이렇게 작성하고 서버를 실행한 뒤,

 

내아이피:포트/yomankum/api-docs 에 접속하면

 

 

 

 

 

내 api 종류와 설명등이 나오고

클릭하묜

 

 

이렇게 편리하게 자동으로 명세서가 생성된다 ^0^/)

 

 

나처럼 귀찮음 MAX 인 사람들에겐

무척 유용하리라...

 

노션에 직접 정리 안 해도 되어서 엄청 편해잉!~

728x90