[개인 프로젝트(3)] API 문서 자동화 도구 선택

개발로그·2023년 10월 19일

개인 프로젝트

목록 보기

3/14

📌 API 문서란

💡 API 문서 : API를 사용하는 방법과 API가 제공하는 기능 및 기능에 대한 설명을 포함하는 문서

API 문서는 다음과 같은 정보를 포함할 수 있다.

API 엔드 포인트 및 요청 방법
: API 엔드 포인트 및 API 요청에 필요한 HTTP 메소드
매개 변수 및 인증
: API 요청에 필요한 매개 변수, 헤더 및 인증 방법
응답 형식
: API가 반환하는 응답 데이터의 형식 및 구조를 설명하는 예제와, 응답의 해석 방법
에러 처리
: API 요청 중 발생할 수 있는 에러 및 에러 코드에 대한 설명
사용 사례 및 예제
: API를 사용하는 예시와 코드 샘플

🥕 API 문서는 API를 사용하는 개발자 및 개발 팀에게 중요한 자원으로,
API를 쉽게 적용할 수 있도록 유용한 정보를 제공하여 개발자가 API를 효과적으로 활용하고 통합하는 데 도움을 준다.

📌 API 문서 자동화는 왜 필요할까?

Google Docs, Spread Sheet, Wiki, Notion 등을 사용해 API 명세를 수동으로 문서화할 수도 있지만, API 문서 자동화를 지원하는 자동화 도구를 사용하면 다음과 같은 이점을 취할 수 있다.

- 개발 생산성 향상
: 수동으로 API 문서를 작성하고 유지하는 것은 비용과 시간이 많이 소요되는 작업이다.
API 문서 자동화 도구를 사용하여 개발 생산성을 향상 시킴으로써, 개발에 집중할 수 있다.

- API 문서의 일관성 향상
: 자동화된 API 문서는 항상 최신 정보를 제공하며, 갱신된 API 엔드포인트, 매개변수 및 응답 형식을 반영할 수 있다.

- 테스트 및 디버깅 용이성 향상
: 개발자는 자동화된 API 문서를 참조하여 정확한 요청 및 응답을 확인하고 API 동작을 디버깅할 수 있다.

🥕 API 문서 자동화 도구를 도입하자!

📌 API 문서 자동화 도구

API 문서 자동화 도구로는 대표적으로 Swagger와 Spring REST Docs가 있다.

여기서는 Swagger와 Spring REST Docs에 대한 공식 문서의 설명을 살펴보고,
아래에서 각 도구가 제공하는 기능들과, 장단점을 더 자세히 알아보자!

✅ Swagger

💡 Swagger는 API의 리소스를 시각화하고 상호 작용할 수 있게 하는 도구이다.
Swagger UI는 OpenAPI 사양에서 자동으로 생성되며 시각적 문서를 제공함으로써, 보다 편리한 API 구현 및 클라이언트 측에서의 API 사용을 지원한다.

종속성 없음
: 로컬이든 웹이든 모든 개발 환경에서 동작한다.
인간 친화적
: 최종 개발자가 쉽게 사용할 수 있도록 API가 공개하는 모든 단일 작업과 쉽게 상호 작용하고 시험해볼 수 있다.

간편한 탐색
: 깔끔하게 분류된 문서를 통해 리소스와 엔드 포인트를 빠르게 찾아 작업할 수 있다.

모든 브라우저 지원
: 모든 주요 브라우저에서 작동하는 Swagger UI를 통해 가능한 모든 시나리오를 충족할 수 있다.

완벽한 OAS 지원
: Swagger 2.0 또는 OAS 3에 정의된 API 시각화
OAS(OpenAPI Specification) : RESTful API를 기 정의된 규칙에 맞게 API spec을 json이나 yaml로 표현하는 방식

( Swagger-ui 공식 문서 )

✅ Spring REST Docs

💡 Spring REST Docs는 RESTful 서비스에 대한 정확하고 읽기 쉬운 문서를 생성하도록 지원하는 도구이다.

고품질 문서 생성 지원 (커스텀이 자유롭다)
일반 텍스트를 처리하고, 필요에 맞게 스타일과 레이아웃을 갖춘 HTML을 생성하는 Asciidoctor로 작성된 문서 와 테스트에서 생성된 스니펫을 결합한다.

또한, 원하는 경우 Markdown을 사용하도록 Spring REST Docs를 구성할 수도 있기 때문에,
Swagger UI로 생성된 문서와는 다르게 제한 사항에서 벗어날 수 있고 높은 자유도를 가질 수 있다.

테스트 기반 API 문서 자동화 도구
: Spring REST Docs는 테스트에서 생성된 스니펫을 사용한다.
스니펫이 올바르지 않으면 이를 생성하는 테스트가 실패하기 때문에, API 문서의 정확성을 보장한다.

HTTP 요청과 응답의 세부 정보를 문서화하고, 이를 통해 서비스의 내부 구현 세부 정보를 감추고 API를 중점적으로 문서화할 수 있다.

Spring Rest Docs(docs.spring.io)
Spring Rest Docs(spring.io)

📌 Swagger VS Spring REST Docs

Swagger

API 테스트 가능
API 문서 생성이 자동으로 이루어진다.
프로덕션 코드에 Swagger 문서화를 위한 어노테이션이 추가된다.

Spring REST Docs

API 테스트 불가
테스트 성공 이후 생성된 스니펫으로 직접 문서를 작성해야 한다.
테스트 코드 작성을 강제하여 API 문서가 신뢰성이 있다.
프로덕션 코드와 문서화를 위한 코드가 분리된다.

📌 Swagger와 Spring REST Docs의 조합

💡 Swagger와 Spring REST Docs를 함께 사용하면,

각각의 장점을 살려 API 문서를 통한 API 테스트를 제공하면서, 테스트 코드 작성을 강제하여 신뢰성 있는 API 문서를 만들 수 있다.

프로덕션 코드와 문서화를 위한 코드가 분리할 수 있다.

아래 사진에서 윗 섹션은 기존 Spring rest docs를 사용했을때의 흐름이고,
아래 섹션은 Spring rest docs에 OpneAPI3와 swaggerui를 통해 합쳤을 때의 흐름이다

Spring REST Docs만을 사용할 때는 Asciidoctor를 통해 문서를 생성하는 반면,
Swagger와 Spring REST Docs를 함께 사용하는 경우, Spring REST Docs 실행 결과를 OpneAPI3 스펙으로 출력하고, 이를 통해 SwaggerUI를 생성하는 방식으로 동작한다.