OpenAPI Specification을 활용한 효율적인 API 문서화

API 문서화 도구인 Swagger는 사용성이 좋지만 테스트 강제가 없어 신뢰도가 낮고 비즈니스 로직에 어노테이션이 섞이는 단점이 있다. 반면 Spring REST Docs는 테스트를 통해 높은 신뢰도를 보장하고 소스코드 오염이 없지만, UI가 미려하지 않고 API 테스트 기능을 지원하지 않는다.

이 두 도구의 장점을 모두 취하기 위해 **OpenAPI Specification(OAS)**을 활용한다. restdocs-api-spec 오픈소스를 이용하면 Spring REST Docs의 테스트 결과를 바탕으로 OAS 파일을 생성할 수 있으며, 이를 Swagger-UI로 시각화하여 사용성을 높일 수 있다.

구현 단계는 다음과 같다:

• Swagger-UI 정적 파일 설치 및 Static Routing 설정
• restdocs-api-spec을 이용한 OAS 파일 생성 빌드 환경 구축
• 생성된 OAS 파일을 Swagger 디렉터리로 복사하는 스크립트 작성
• MockMvc를 활용한 REST Docs 테스트 코드 작성