Spring boot - Api docs 설정 (Swagger + OpenAPI) 본문
반응형
이번 포스팅은 스프링부트에서 Api docs를 설정하는 방식에 대해 다룬다.
(아마 다음 포스팅은 GraphQL 설정 방식에 대해 다룰 듯 싶다.)
Api docs를 사용하기 있어, 먼저 해당 기능 사용을 돕는 라이브러리를 추가한다.
// build.gradle
dependencies {
implementation 'org.springframework.boot:spring-boot-starter-web'
// Swagger
implementation 'org.springdoc:springdoc-openapi-starter-webmvc-ui:2.5.0'
implementation 'org.springdoc:springdoc-openapi-starter-common:2.5.0'
implementation 'io.swagger.core.v3:swagger-annotations:2.2.20'
// 중략
}
여기서, org.springdoc의 버전은 1.8.0 | 2.3.0 | 2.5.0 이 존재하니 자신이 원하는 버전으로 설치하면 될 것 같다.
이후 Swagger UI 기본 경로 및 문서 경로를 설정한다.
// application.yml
springdoc:
swagger-ui:
enabled: true
path: /swagger-ui.html // Swagger ui 접근 경로
operationsSorter: method // 메소드 정렬
tagsSorter: alpha // 태그 알파벳순 정렬
tryItOutEnabled: true
filter: true // 필터
urls:
- url: /v3/api-docs
name: Chessy API
api-docs:
enabled: true
path: /v3/api-docs // open api 스펙 json 경로
default-produces-media-type: application/json
default-consumes-media-type: application/json
이후 각 컨트롤러에
@Tag, @Operation 어노테이션으로 Swagger가 적용됨을 명시하며, 설명을 덧붙일 수 있다.
// AppController.java
package com.chessy.controller;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;
import com.chessy.exception.CustomException;
import com.chessy.exception.ErrorCode;
import io.swagger.v3.oas.annotations.Operation;
import io.swagger.v3.oas.annotations.tags.Tag;
@Tag(name = "AppController", description = "기본 API")
@RestController
@RequestMapping("/api/")
public class AppController {
@Operation(summary = "헬스 체커", description = "애플리케이션 상태 확인 API")
@GetMapping("/")
public String healthCheck() {
return "ok";
}
@Operation(summary = "테스트 API", description = "예외 처리 테스트용 API")
@GetMapping("/test")
public String test() {
throw new CustomException(ErrorCode.USER_NOT_FOUND);
}
}
보통은 여기까지하면 아래 주소로 접속이 가능하다.
/swagger-ui.html
하지만, 언제든 api 버전 관리는 필요하기 때문에 커스텀 하는 방법도 소개한다.
// Spring.Config.java
@Configuration
public class SpringConfig implements WebMvcConfigurer {
// 중략
@Bean
public OpenAPI customOpenAPI() {
return new OpenAPI()
.info(new Info()
.title("Test API") // 제목
.version("1.0.0") // 버전
.description("API 문서") // 설명
.contact(new Contact()
.name("zynoobb") // 작성자
.email("jw9491@gmail.com")) // 연락처
.license(new License()
.name("Apache 2.0")
.url("http://springdoc.org")));
}
}
이와 같은 방식으로 해당 내용을 추가해줄 수 있다.
추가로, 위 html 주소를 일일히 외워쓰기 번거롭다면 아래와 같은 방법을 사용할 수 있다.
// SwaggerController.java
package com.**.controller;
import org.springframework.stereotype.Controller;
import org.springframework.web.bind.annotation.GetMapping;
@Controller
public class SwaggerController {
@GetMapping("/api")
public String redirectSwagger() {
return "redirect:/swagger-ui/index.html";
}
}
/api 로 접속 시, 내 swagger 주소로 리디렉션하는 방식으로
URI 뒤에 api 로 접속하면 스웨거로 빠르게 접속할 수 있다.
ps. 자바스크립트 기반 프레임워크 같은 경우는,
swagger를 작성함에 있어 api에서 사용하는 인풋값의 타입을 직접 지정해주어야 하는 불편함이 있었는데,
스프링부트의 경우 아직까지는 그럴 필요가 없어서 꽤 만족스럽다.
반응형
'개발 > Spring boot' 카테고리의 다른 글
Spring boot - GraphQL 적용하기 (1) | 2025.05.16 |
---|---|
Spring boot - Custom Global exception Handler 적용 (1) | 2025.05.04 |
Spring boot - Docker-compose hot loading 환경 설정(with, vscode) (0) | 2025.04.25 |
Spring boot - 패키지가 정상 빌드되지 않을 때(Gradle) (1) | 2025.04.11 |
Java - 버전이 정상적으로 지정되지 않을 때 (셀 스크립트) (0) | 2025.04.07 |
Comments