Spring Boot 에 Swagger 를 설정하고자 합니다.
Swagger 란?
Swagger는 API 문서화 및 테스트 도구로, 개발자가 RESTful API를 쉽게 문서화하고 사용할 수 있도록 도와주는 오픈 소스 프레임워크입니다. Swagger를 사용하면 API의 구조, 엔드포인트, 요청 및 응답 형식 등을 명확하게 정의하여 개발자들이 API를 이해하고 사용하는 데 도움이 됩니다.
설정 방법
먼저 라이브러리를 추가해주어야 합니다.
swagger 라이브러리로는 springfox / springdoc 이 있는데, springfox 는 이제 더 이상 업데이트를 하지 않아 springdoc 을 사용하는 것이 좋습니다!
** Spring Boot 3.0 이상 부터는 springdoc-openapi-starter-webmvc-ui 를 사용하셔야 합니다!!
// gradle
implementation("org.springdoc:springdoc-openapi-starter-webmvc-ui:2.0.4")// Maven
<dependency>
<groupId>org.springdoc</groupId>
<artifactId>springdoc-openapi-starter-webmvc-ui</artifactId>
<version>2.0.2</version>
</dependency>3.0 이전 버전의 경우는 org.springdoc:springdoc-openapi-ui 를 사용하시면 됩니다.
사실 이렇게만 설정해줘도 기본적으로 controller 들을 자동으로 scan 하여 적당하게 화면을 보여줍니다.
하지만 이렇게 아래 부분이 Default 로 설정된 값으로만 보여줘 이런 부분을 설정해 줄 수 있습니다!
SwaggerConfig.java 파일 작성을 통해 title, description 등을 설정해보겠습니다.
package com.junam.my_bucket_server.config;
import io.swagger.v3.oas.models.Components;
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()
.components(new Components())
.info(apiInfo());
}
private Info apiInfo() {
return new Info()
.title("My Bucket List")
.description("My Bucket List API")
.version("1.0.0");
}
}다음과 같이 설정하면 아래와 같이 보이게 됩니다. 간단하죠?
이제 추가적으로 해주면 좋은 Controller 파일 별로 Tag 를 설정해주는 방법이 있습니다.
package com.junam.my_bucket_server.controller;
import io.swagger.v3.oas.annotations.tags.Tag;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;
@Tag(name= "TEST API")
@RestController
@RequestMapping("/api")
public class TestController {
@GetMapping("/hello")
public String hello() {
return "hello";
}
}Tag 어노테이션을 통해 각 Controller 별 이름 등을 설정해 줄 수 있습니다.
좀 더 자세하게는 각 함수 별로 요약, 설명과 각 파라미터 등에 대해 설명을 해주고 성공, 실패 시 어떤 것을 리턴해주는지도 확인해 볼 수 있는데 이는 공식 가이드에 잘 나와 있으니 한 번 확인해보시면 좋을 것 같습니다. (https://springdoc.org/)
