API 문서화

• 클라이언트가 API를 사용하기 위해서 알아야 하는 "요청 정보"를 문서로 정리한 것을 말한다.
  • 요청 URI/URL
  • request body
  • query parameter

• API 사용을 위한 어떤 정보가 담겨 있는 문서를 API 문서 또는 API 스펙(사양, Specification)이라고 한다.

Swagger

보통 Java 기반의 애플리케이션에서는 Swagger라는 API 문서 자동화 오픈소스를 많이 사용한다.

• 애너테이션 기반의 API 문서화
• 장점: API 요청 툴로써의 기능을 사용할 수 있다.
• 단점
  • 수많은 애너테이션들로 인해, 코드가 늘어나고 복잡해진다.
    => 코드의 가독성 ⬇️
  • API 스펙 정보와 API 문서 내의 정보가 일치하지 않을 수도 있다.

Spring Rest Docs

이런 Swagger의 단점으로, 우선 Spring Rest Docs로 문서화를 해보려고 한다.

• REST API 문서를 자동으로 생성해주는 Spring 하위 프로젝트
• 테스트 코드 기반의 API 문서화

장점

1. 애플리케이션 코드에 문서화를 위한 정보들이 Swagger에 비해 적게 포함된다.
   (작성할 코드가 아예 없는 건 아니다! 꽤 있다!)

2. 테스트 케이스의 실행이 “passed”여야 API 문서가 생성된다.

   => 테스트 케이스에서 전송하는 API 문서 정보와 Controller에서 구현한 Request Body, Response Body, Query Parameter 등의 정보가 하나라도 일치하지 않으면 테스트 케이스의 실행 결과가 “failed” 되면서 API 문서가 정상적으로 생성이 되지 않는다.

   => 애플리케이션에 정의되어 있는 API 스펙 정보와 API 문서 정보의 불일치로 인해 발생하는 문제를 방지할 수 있다.

단점

1. 테스트 케이스를 일일이 작성해야하고, Controller의 모든 테스트 케이스를 “passed”로 만들어야 한다.

2. Swagger와 다르게, API 툴로써의 기능은 제공하지 않는다.

API 문서 생성 흐름

1. 테스트 코드 작성
   a. Controller 슬라이스 테스트 코드 작성
   b. API 스펙 정보 코드 작성

2. 테스트 실행
   -> Gradle의 빌드 태스크인 test task를 실행시켜 API 문서 스니핏을 일괄 생성한다.

3. API 문서 스니핏(.adoc) 생성

   • 스니핏(snippet): 코드/문서의 일부 조각을 의미
   • .adoc 확장자를 가진 파일로 생성됨
   • 테스트 케이스 하나 당 하나의 스니핏이 생성되고, 여러 스니핏이 모여 API 문서를 생성함

4. API 문서 생성
   -> 여러 스니핏이 모여 하나의 API 문서를 생성함

5. API 문서 -> HMTL로 변환
   -> HTML 파일로 공유할 수 있음

---

1 & 2. 테스트 코드 작성 및 실행

이전에 배웠던 테스트 코드를 그대로 작성한 후에, 마지막에 API 스펙 정보를 추가해준다.

postMember() 핸들러 메서드에 대한 API 문서를 작성해보자.

a) Controller 슬라이스 테스트 코드 작성

a-1) Mockito를 사용해서 다른 계층과의 연결을 끊는다.

MemberController는 MemberService와 MemberMapper와 의존관계를 맺고 있다.
이는 슬라이스 테스트이기 때문에 의존하는 다른 계층의 객체와는 관계를 단절해야 하므로 Mockito를 사용해야 한다.

우리의 관심사는 MemberController가 요청을 잘 받고, 응답을 잘 전송하는지 뿐이다.
(비즈니스 계층과 매핑 과정은 신경쓰지 않아!)

따라서 MemberService와 MemberMapper에 Mock Bean을 주입받는다.

a-2) Mock 객체를 통해서 Stubbing + POST 요청을 실행

b) API 스펙 정보 코드 작성

RestDocumentationResultHandler

• 실질적인 문서화 작업을 수행하는 클래스

document() 메서드

• RestDocumentationResultHandler 클래스의 메서드 중 하나

1) 스니핏의 식별자 설정
2) OperationRequestPreprocessor/OperationResponsePreprocessor: request와 response에 대한 전처리 과정
3) requestFields(): request body의 데이터를 표현
4) responseHeaders(): response header를 표현

5) pathParameters(): URI에 있는 PathVariable에 대한 정보를 설정
6) responseFields(): response body의 데이터를 표현

---

3 & 4. API 문서 생성

하나의 테스트 케이스는 하나의 스니핏을 생성한다.
그리고 여러 스니핏이 모여 하나의 API 문서가 완성된다.
이때 여러 스니핏을 작성해둘 API 문서 템플릿이 존재해야 한다.

a) API 문서 템플릿 생성

• Gradle 프로젝트의 경우, 템플릿 문서가 위치하는 디폴트 경로가 “src/docs/asciidoc”이다.
• 템플릿에서 스니핏을 사용할 때는, include::{snippets}/스니핏 문서가 위치한 디렉토리/스니핏 문서파일명.adoc[]라고 작성한다.

---

5. API 문서를 HTML로 변환

1) Gradle의 :build 또는 :bootJar task 명령을 실행한다.

2) 정상적으로 빌드가 완료되면, src/main/resources/static/docs 디렉토리에 index.html 파일이 생성된다.

3) 해당 html 파일을 웹 브라우저에서 연다.