[API문서화] Spring Boot 3.x 버전 Swagger 적용하기

---

필요성

기존에는 프로젝트 진행할 때는 따로 API 문서를 만들지 않고 진행했던 기억이 난다.3

그때 당시에는 JSON 텍스트 형식으로 프론트엔드 분과 데이터 모양 합의하고, 추가로 변경된 내용들이 있다면 메모했던 내용들을 가지고 다시 가져가 서로 맞추고 하는 과정들을 했던 것으로 기억한다. 매우 번거롭다

API 문서화 자동화 라이브러리를 이용한다면,  API 호출시 반환될 데이터의 모양을 미리 볼 수도 있고 중복된 API를 개발하거나 불필요한 API들을 한눈에 알아보기 쉬운 장점이 있다.

 

Spring Boot 기반 프로젝트에서는 일반적으로 2가지의 API 문서화 툴을 사용하는데 장단점을 알아보고 비교해보자

	Swagger (OpenAPI)	Spring REST Docs
문서 자동화 방식	코드 어노테이션 기반	테스트 코드 기반
코드와 문서 동기화	자동화 지원
정확성	높은 정확성
장점	간편하고 빠르게 문서화 가능, 자동생성 UI 제공	테스트와 연동되어 높은 신뢰성 제공
단점	코드에 어노테이션 많아짐(코드 복잡도 증가)	초기 설정 및 작성 난이도가 있음

 

목적별로 나누어보자

• Swagger
  
  • 빠른 문서화 작업을 원할 때
  • API가 자주 변경되거나 초기 개발 단계일 때
  • 프론트엔드와 빠르게 소통할 때
• Spring REST Docs
  • 완성도 높은 문서를 유지보수 단계에서도 제공할 떄
  • 테스트 코드 기반으로 정확하고 안정적인 문서화를 원할 때
  • 문서가 반드시 검증된 상태를 유지해야 할 때

 

정리

Swagger : 초기 개발, 비교적 변경이 많은 시기에 사용

Spring REST Docs : API 변경 시 문서화 업데이트를 필수로 해야할 때 (비즈니스적으로 API 변경 추적이 중요할 때)

 

---

필자는 현재 개발 초기의 프로젝트를 진행하고 있고, 단위테스트를 개발하며 할 시간이 없는 관계로 Swagger로 적용하였고, 추후 프로젝트 규모가 커진다면 Spring REST Docs와 혼용할 예정이다.

 

Spring Boot 프로젝트에 적용해보기

버전 정보
Spring Boot : 3.x 버전
Swagger : 2.8.5

 

 

1. build.gradle 에 의존성 추가

dependencies {
	// API 관련 (문서화)
	implementation 'org.springdoc:springdoc-openapi-starter-webmvc-ui:2.8.5'
}

 

2. Application.yml 설정 추가

springdoc:
  swagger-ui:
    path: /swagger-ui.html
  api-docs:
    path: /api-docs

 

3. Controller에 어노테이션 추가

@RestController
@RequestMapping("/test")
@Tag(name = "TEST API", description = "TEST API")
public class ExerciseController {

    @Operation(summary = "TEST 조회", description = "Swagger 테스트 조회입니다.")
    @GetMapping
    public ResponseEntity<List<TestDto>> 함수명() {
        return ResponseEntity.ok(...);
    }
}

 

결과 확인(로컬 환경에서 확인이 가능하다. http://localhost:포트번호/swagger-ui.html)