OpenAPI Specification을 이용한 더욱 효과적인 API 문서화

본 글은 카카오페이 증권플랫폼파트에서 Spring 기반 서버 프로젝트의 API 문서화 경험을 공유합니다. 기존에 많이 사용되는 Swagger와 Spring REST Docs는 각각 장단점을 가지고 있습니다.

Swagger는 편리한 UI와 API 테스트 기능을 제공하지만, 테스트를 강제하지 않아 문서의 신뢰도가 낮아질 수 있고 비즈니스 로직과 어노테이션이 섞이는 단점이 있습니다. 반면 Spring REST Docs는 Integration 테스트를 통해 문서를 작성하므로 신뢰도가 높고 비즈니스 로직과 테스트를 분리할 수 있지만, 문서의 미려함과 API 테스트 기능이 부족하다는 단점이 있습니다.

본 글에서는 사실상의 표준으로 자리 잡고 있는 OpenAPI Specification(OAS)을 활용하여 Swagger와 Spring REST Docs의 장점을 결합하는 방법을 소개하고, 이를 통해 더욱 효과적인 API 문서화를 달성하는 방안을 제시합니다.