들어가기에 앞서
OpenAPI Specification 라고 알려진 OAS는 RESTful API를 기술하는 표준이다.
Wikipedia에선 이 OpenAPI Spec을 다음과 같이 설명한다.
The OpenAPI Specification, previously known as the Swagger Specification, is a specification for a machine-readable interface definition language for describing, producing, consuming and visualizing web services.
간단하게 설명하면, 웹 서비스의 API 기능과 정보를 제공해주는 표준 이라고 할 수 있겠다. 이런저런 스토리가 있긴 하지만, 보통 Swagger 라는 ui tool을 이용해 문서를 작성한다.
본 포스트에서는 API 문서를 관리하기 위해 Swagger 를 도입한 내용을 정리한다.
방법
인턴 시절, AI 모델 서빙을 위해 FastAPI로 간단한 서버를 구현한 적이 있다. FastAPI는 신기하게도 자동으로 Swagger 문서를 만들어주는데, Springboot 또한 비슷한 기능을 지원한다.
첫번째 방법
Springboot는 springdoc 이라는 라이브러리를 사용하면 코드에 어노테이션을 작성하는 것으로 API 문서를 만들 수 있다.
아래와 같이 의존성을 추가하고
implementation 'org.springdoc:springdoc-openapi-starter-webmvc-ui:2.3.0'
어노테이션 기반으로 메타데이터를 작성해준다면, 어플리케이션 실행 시 API 문서가 생성되는 것을 볼 수 있다.
@Tag(name = "error pages", description = "에러 페이지 매핑 정보")
public class ClassName {
@Operation(summary = "error 500", description = "500 에러 발생 시 호출됩니다")
public String methodName() {
...
}
}이 방법은 어노테이션 기반으로 작성하기에 굉장히 편리하다는 장점이 있다. 다만, 몇가지 단점이 존재한다.
- API 문서를 위한 어노테이션이 비즈니스 소스 코드를 오염시킴
- 서버를 실행시켜야 API 문서를 볼 수 있음
이러한 단점들을 해결하기 위해 필자는 다른 방법을 사용했다.
두번째 방법
필자가 선택한 방법은 직접 API 문서를 작성하는 것이다.
Swagger Editor 를 이용해 문서를 직접 작성하고, 해당 문서 파일을 Git을 통해 관리하고 있다.
이러한 방법을 채택함으로써 얻은 이점은 다음과 같다.
- API 문서와 비즈니스 소스 코드가 전혀 섞이지 않음
- 서버를 실행시키지 않고도 문서를 얼마든지 읽을 수 있음
- Git을 통해 문서 버전을 관리하기에 변경 추적에 유리함
다만, 기존 어노테이션 기반 방법보다 작성하기 불편하다는 단점이 존재한다.
세번째 방법
카카오페이 기술 블로그 에서 관련 내용을 찾을 수 있었다.
기존의 단점인 비즈니스 소스 코드의 오염을 방지하며, Spring REST Docs 라이브러리의 장점까지 포함한 문서 관리 방법이다.
다만, 1인 개발의 경우 해당 문서화 시스템을 구축하는 것이 큰 부담으로 다가왔기에 보다 간단한 두번째 방법을 선택했다.
결론
MSA 기반의 프로젝트를 진행하며 이런 저런 고민들을 하고 있다.
각각의 마이크로 서비스가 존재하는 구조이다 보니, 어노테이션을 소스 코드에 추가하여 문서를 작성하는 첫번째 방법은 불편하다고 생각했으며, client의 관점에서 필요한 API를 찾기 위해 여러 문서를 뒤지는 것은 불편할 것이라고 생각했다.
모든 마이크로 서비스의 API들을 한 곳에서 관리하기 위해 직접 문서를 작성하게 되었고, 문서는 Git을 통해 버전 관리를 진행하고 있다.
참고 자료
OAS(OpenAPI Specification)
springdoc
카카오페이 기술 블로그 - openAPI spec
