Springdoc-openapi-ui로 Swagger3 사용하기

Swagger란?

• Open Api Specification(OAS)를 위한 프레임워크이다.
• API들이 가지고 있는 스펙(spec)을 명세, 관리할 수 있는 프로젝트/문서
• API 사용 방법을 사용자에게 알려주는 문서
• Springboot에서 Swagger를 사용하면, 컨트롤러에 명시된 어노테이션을 해석하여 API문서를 자동으로 만들어준다.
• 참고로 Swagger는 Java에 종속된 라이브러리가 아니다.
• URL에 /swagger-ui.heml으로 접근하면 swagger가 만들어주는 페이지에 접근할 수 있다.
• 공식 사이트

Swagger를 설정하는 위한 라이브러리는 2가지가 있다.

Spring-Fox,  Spring-Doc 2가지 중에 사용하면 된다.

 

Spring-Fox

• 약 2015년정도에 나온 라이브러리다.
• 2020년 이후로 업데이트가 되고 있지 않는다.
• 그래서 Spring Boot 2.6이상 버전에서는 바로 적용이 되지 않는다.
• 참고 URL

Spring-Doc

약 2019년에 나온 라이브러리 이다.

업데이트가 최근까지도 이루어지고 있다.

Spring Boot 2.6이상 버전에서도 지원이 된다.

 

SpringDoc OpenAPI UI 사용법

아래 링크에서 원하는 버전의 dependency를 가져와서 maven 기준 pom.xml, gradle 기준 build.gradle에 넣어준다.

https://mvnrepository.com/artifact/org.springdoc/springdoc-openapi-ui

 

하지만 SpringBoot 버전이 3이거나 그 위라면 해당 dependency는 작동하지 않는다.

 

스택오버플로우의 답변을 참고하여 스프링부트 3.0이상의 버전에서도 Swagger 3버전을 사용하게 해주는 고마운 dependency가 있어서 소개한다.

 

https://mvnrepository.com/artifact/org.springdoc/springdoc-openapi-starter-webmvc-ui/2.0.2

 

위 링크에서 아래와 같이 

@GetMapping("/api 경로") 혹은 @PostMapping("/api 경로")
@ResponseBody
@Operation(
      method = "POST",
      summary = "API 이름",
      description = "API 설명")
@Parameters(
      {
            @Parameter(
                  name = "파라미터 이름"
                  , description = "파라미터 설명"
                  , required = 필수유무
                  , schema = @Schema(type = "데이터 타입")
            ),