API 문서 자동화 (Feat. Spring API 문서화 도구 비교)
이전에 테크니컬 라이팅 기술과 테크니컬 라이터라는 직업에 관련된 내용의 게시글을 작성한 적이 있다. 이번 문서에서는 테크니컬 라이팅 업무 중 하나인 API 문서화와 Spring 프로젝트에서 API 문서화를 하기 위해 어떤 프레임워크를 사용해야 되는 지에 대해서 알아보려고 한다.
API 문서와 API 문서 자동화
API 문서
정의
API 문서화는 문서 엔지니어링이 가장 많이 적용되는 분야이다. API 문서는 API 레퍼런스라고도 불리며, API 사용을 위한 어떤 정보가 담겨 있는 문서이다. 직접 수기(Notion 등)로 작성할 수도 있지만, 일반적으로 애플리케이션 빌드를 통해 API 문서를 자동 생성하는 경우가 많다.
필요성
사용자 지원
개발자나 시스템 사용자에게 API를 올바르게 사용하는데 도움을 준다. 또한, 명확하고 자세한 설명을 통해 사용자가 API를 효율적으로 활용할 수 있도록 지원한다.
개발 시간 단축
개발 과정에서 시간을 단축시킬 수 있다. 문서화된 API는 개발자에게 필요한 정보를 제공하여 API를 효과적으로 사용할 수 있도록 도와준다. 이는 개발자가 API를 테스트하고 통합하는데 소요되는 시간과 노력을 줄일 수 있다.
통신 및 협업
API를 제공하는 조직 또는 팀 내에서 효과적인 커뮤니케이션과 협업을 도와준다. API 문서를 통해 다른 개발자나 팀원들이 API의 사용법과 기능을 이해하고, 일관된 방식으로 작업할 수 있도록 한다.
내용
- API 개요 : 어떤 기능을 제공하는 API인지, 사용자가 API를 어떻게 활용할 수 있는지에 대한 간단한 소개 등
- 엔드포인트 및 요청 방법 : API가 제공하는 엔드포인트와 각각의 요청 방법(GET, POST, PUT, DELETE 등)에 대한 설명, 각 엔드포인트의 경로와 매개변수에 대한 정보
- 요청과 응답 : 요청에서 필요한 매개변수와 헤더, 요청 본문 형식 설명, 응답에서는 반환되는 상태 코드와 응답 본문 형식에 대한 정보 필요
- 매개변수/페이로드와 예시 : 매개변수와 페이로드의 이름, 타입, 설명, 필수 여부, 기본 값 등을 명시하고, 실제 예시를 통한 매개변수를 사용하는 방법을 제공해야 함
- 응답 본문 : JSON, XML 등의 형식을 사용하거나, 특정 필드의 값을 설명해야할 수도 있음
- 에러 처리 : API에서 발생할 수 있는 에러 상황과 그에 대한 응답에 대한 설명을 포함해야 함. (ex: 잘못된 요청이나 인증 오류에 대한 응답 코드와 에러 메시지 설명)
- 인증과 권한 : API의 인증 방법과 필요한 권한에 대한 정보를 제공해야 함 (ex: API 키, OAuth 인증, 토큰 기반 인증에 대해 설명하고, 각각의 인증 방법을 사용하는 방법에 대한 예시 제시)
- 버전 관리 : API의 버전 관리 방법과 업데이트 사항에 대한 정보를 포함해야 함. 개발자들이 이전 버전과 새 버전 간의 호환성을 확인할 수 있도록 업데이터 사항을 제공해야함
API 문서 자동화
기존의 수동적인 문서 작성 절차를 자동화하여 API의 문서를 생성하는 프로세스를 의미한다. 일반적으로 API의 메타데이터, 주석, 주요 기능 등을 추출하고 구조화하여 문서 형식으로 변환하는 도구나 프레임워크를 사용한다. 이를 통해 개발자들은 API를 업데이트하거나 변경할 때마다 수동으로 문서를 수정하거나 갱신할 필요 없이 자동화된 프로세스를 통해 문서를 생성하고 유지할 수 있다.
장점
시간 절약
API 문서를 수기로 작성하게 되면 해당 페이지 혹은 정적 문서의 디자인, 가독성 등에 신경을 써야하므로 개발에 소요되는 시간보다 문서를 작성하는 데 드는 시간이 더 소요될 것이다. 결론적으로는 배보다 배꼽이 커지는 것이다.
정확성 보장
만약 기존에 작성된 API 문서가 있고, 해당 API에 대해 개발자가 수정을 하여, 요청 혹은 응답이 달라졌다고 생각해보자. 만약 수기로 API 문서를 관리한다고 했을 때, 개발자가 이를 업데이트 하지 않았을 경우 제공된 API 정보와 작성된 API 문서의 정보가 달라서 문제가 생길 것이다. API 문서 생성을 자동화한다면 이러한 시간적 비용과 걱정을 해소할 수 있을 것이다.
일관성 유지
수기로 작성된 API 문서의 경우에는 사람마다 스타일이나 형식이 달라질 수 있지만, 자동화된 프로세스를 통해 일관된 형식과 구조를 유지할 수 있기 때문에 개발자들이 통일된 방식으로 API를 이해하고 사용할 수 있다.
Spring Boot의 API 문서 자동화 툴
작성 배경
이번 프로젝트에서 백엔드 파트를 담당하여, Spring Boot를 통한 API 서버 개발을 하게 되었다. API 개발 시 프론트엔드 팀원과 좀 더 편하게 소통하기 위해 API 문서 생성을 자동화하도록 결정하였고, 이를 위해 Swagger와 Spring RestDocs 중 어떤 프레임워크가 현재 우리 상황에 더 맞는지 알아보기로 하였다.
Swagger
API 개발과 문서화를 위한 오픈 소스 프레임워크이다. Swagger를 통해 API의 스펙을 정의하고, 자동으로 인터렉티브한 문서를 생성하고, 테스트할 수 있는 환경을 제공할 수 있다.
장점
쉬운 설정 : 어노테이션과 구성 설정을 사용하여 API 문서를 자동으로 생성하기 때문에, 간단한 설정만으로도 Swagger UI를 사용하여 인터렉티브하고 시각적으로 매력적인 API 문서를 제공할 수 있다.
실시간 문서 업데이트 : Swagger 스펙 파일을 기반으로 문서를 동적으로 생성하므로, API 변경 시 실시간으로 문서가 업데이트된다. 이를 통해 개발자들은 항상 최신화된 API 문서를 확인할 수 있다.
API 탐색 기능 : 사용자가 API를 시각적으로 탐색하고 테스트할 수 있는 기능을 제공한다. 요청 매개변수를 조작하고 실행하여 실제 응답을 확인할 수 있다.
단점
가독성 저하 : 로직에 어노테이션을 통해 명세를 작성하게 되므로, 명세를 위한 코드들이 많이 붙게 되어 전체적으로 가독성이 떨어질 수 있다.
정확성 우려 : 테스트 기반이 아니기 때문에 API 문서의 정확도가 100%라고 확신할 수 없다.
오류에 대한 문서화 불가능 : 모든 오류에 대한 여러 가지 응답을 문서화할 수 없다.
Spring RestDocs
Spring 프레임워크 기반의 API 문서 자동화 도구로, 테스트 기반으로 API 문서를 생성하여, API 문서의 정확성과 일관성을 유지하면서 개발자가 테스트 코드를 작성하고 유지할 수 있도록 한다. 이를 통해 API 문서의 업데이트와 유지보수를 용이하게 할 수 있습니다.
장점
테스트 기반 문서 생성 : 테스트 코드를 기반으로 API 문서를 자동으로 생성한다. 테스트를 작성하고 실행하면 테스트 결과를 문서로 변환하여 정확하고 신뢰할 수 있는 문서를 생성한다.
다양한 문서 형식 지원 : Asciidoctor를 사용하여 다양한 문서 형식(Markdown, HTML 등)으로 변환할 수 있다. 이는 다양한 플랫폼이나 도구에서 문서를 활용할 수 있는 유연성을 제공한다.
코드와 주석 기반 문서화 : 코드와 주석에서 정보를 추출하여 문서를 생성하므로, 개발자들은 코드 변경 시 주석을 업데이트하는 것을 잊지 않고 API를 정확하게 문서화할 수 있다.
단점
필수적인 테스트 코드 작성 : 테스트 기반으로 API 문서 생성을 자동화하기 때문에, API 동작을 검증하는 테스트 케이스를 작성해야 한다.
인터렉티브 기능 부족 : Swagger와 달리 인터렉티브한 API 탐색 기능을 제공하지 않기 때문에, 생성된 문서를 통해 직접 요청을 테스트하거나 검증하기 위해서는 다른 도구나 환경을 사용해야 할 수 있다.
추가 사항
어느 블로그의 게시글에서 Swagger와 Spring RestDocs 두 가지 모두를 사용한 경우를 찾을 수 있었다. Swagger와 Spring RestDocs 모두 각각의 장단점이 있다는 것을 알게 되었고 하나를 사용하면 남은 하나의 장점을 가질 수 없기 때문에, 나중에 한 번 읽어보고 프로젝트 진행 시에 참고해보는 것도 좋을 것 같다.
Reference
API Documentation
- https://engineering.linecorp.com/ko/blog/document-engineering-api-documentation
- https://velog.io/@bagt/API-%EB%AC%B8%EC%84%9C%ED%99%94%EC%99%80-Spring-Rest-Docs
