[Spring] API 문서화 - Spring Rest Docs

API 문서화란? :

클라이언트가 REST API 백엔드 애플리케이션에 요청을 전송하기 위해서 알아야 되는 요청 정보(요청 URL(또는 URI), request body, query parameter 등)를 문서로 잘 정리하는 것

 

 

API 문서 (= API 사양) :

API 사용을 위한 정보가 담겨있는 문서

 

 

API 문서 생성의 자동화가 필요한 이유 :

API 문서를 수기로 직접 작성하는 것이 비효율적 이기 때문에! (수정 필요할 경우 일일히 바꾸기 어려움)

작업 시간 단축하고, 애플리케이션 완성도를 높이기 위해 API 자동화가 필요한 것!

 

 

Spring Rest Docs   vs   Swagger

: 둘 다 API 문서 자동화 오픈소스

 

 

차이점 ? 

 

Swagger -

적용 방식 : 어노테이션들이 애플리케이션 코드(Controller, DTO..)에 추가됨

기능이 늘어나면 늘어날 수록 코드도 추가됨, 기능 구현 코드들의 가독성 떨어짐

 

but Postman 처럼 API 요청 툴로써의 기능 사용 가능

 

↕

 

Spring Rest Docs -

적용 방식 : test 코드들에 추가됨

테스트 케이스의 실행 결과가 'passed' 일 경우에만 생성됨 (개발자 친화적)

(= API 스펙 정보와, API 문서 정보가 일치함)

 

---

Spring Rest Docs의 API 문서 생성 흐름

 

 

1. 테스트 코드 작성

• 슬라이드 테스트 코드 작성
• API 스펙 코드 작성

2. test 태스크 실행

• 작성산 슬라이스 테스트 코드 실행 (gradle의 test task)
• 테스트 실행 결과가 "passed"일 경우만 스니핏 생성됨

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

• 테스트 코드에 포함된 API 스펙 정보 코드 기반,
• API 문서 스니핏 생성됨 (.adoc 확장자)

4. API 문서 생성

• 스니핏 = 문서의 일부 조각 (1 테스트케이스 1 스니핏)
• 생성된 API 스니핏들을 모아서 하나의 API 문서로 생성

5. API 문서 ➡ HTML 로 변환 

• 생성된  API 문서를 HTML로 변환
• HTML 파일 자체 or URL 로 확인 가능

 

* Asciidoctor : .adoc 문서 스니핏을 생성해줌

---

슬라이스 테스트 코드 작성 → API 스펙 정보 코드 작성 → test 태스크 실행 → API 문서 스니핏 생성

→ 스니핏을 포함한 API 문서 생성 → .adoc 파일의 API 문서를 HTML로 변환

---

API 문서 생성을 위한 테스트 케이스 기본 구조

@WebMvcTest(MemberController.class) 
@MockBean(JpaMetamodelMappingContext.class)
@AutoConfigureRestDocs 
public class MemberControllerRestDocsTest {
    @Autowired
    private MockMvc mockMvc;  

    @MockBean
	  // 테스트 대상 Controller 클래스가 의존하는 객체를 Mock Bean 객체로 주입 받기

    @Test
    public void postMemberTest() throws Exception {
        // given
        // 테스트 데이터 

        // Mock 객체를 이용한 Stubbing

        // when
        ResultActions actions =
                mockMvc.perform(
                     // request 전송
                );

        // then
        actions
                .andExpect(// response에 대한 기대 값 검증)
                .andDo(document(
                
                            // ★★★ 여기에 API 문서 스펙 정보 추가 ★★★
                            
                 ));
    }
}

 

given, when, then 을 기반으로 한 테스트 케이스 코드를 작성하는 것은 동일함

but then 부분에서 

 

//then
...
.andDo(document( //API 스펙 정보 전달받아서 실질적 문서화 작업 수행
                        "post-member", //스니핏 식별자 역할 (디렉토리 위치)
                        
            //스니핏 생성 전처리
            // getRequestPreProcessor(),  
            // getResponsePreProcessor(),   
                       
                //문서로 표현될 request body
                requestFields(         
                      List.of(
                        //fieldDescriptor : JSON 포맷시 하나의 프로퍼티
                             fieldWithPath("email").type(JsonFieldType.STRING).description("이메일"), 
                             fieldWithPath("name").type(JsonFieldType.STRING).description("이름"),
                             fieldWithPath("phone").type(JsonFieldType.STRING).description("휴대폰 번호")
                               )
                        ),
                 //문서로 표현될 response body
                 responseFields(    
                        List.of(
                          //fieldWithPath(data.*) : data 프로퍼티의 하위 프로퍼티 
                              fieldWithPath("data").type(JsonFieldType.OBJECT).description("결과 데이터"),
                              fieldWithPath("data.memberId").type(JsonFieldType.NUMBER).description("회원 식별자"),
                              fieldWithPath("data.email").type(JsonFieldType.STRING).description("이메일"),
                              fieldWithPath("data.name").type(JsonFieldType.STRING).description("이름"),
                              fieldWithPath("data.phone").type(JsonFieldType.STRING).description("휴대폰 번호"),
                              fieldWithPath("data.memberStatus").type(JsonFieldType.STRING).description("회원 상태"),
                              fieldWithPath("data.stamp").type(JsonFieldType.NUMBER).description("스탬프 갯수")
                                )
                        )
                ));

 

* .description 뒤에 붙일 수 있는 프로퍼티들

 

.description(어쩌구).ignored() : API 스펙 정보에서 제외

.description(어쩌구).optional() : API 스펙 정보에서 선택 정보로 설정

 

 

 

테스트 케이스 실행 후 결과가 passed 일 경우

문서 스니핏들이 생성됨

 

 

왼쪽 : 생성된 문서 스니핏 (http-request.adoc)

오른쪽 : Asciidoc 형태로 작성된 내용이 문서로 렌더링된 모습

---

지금까지 만든 것은 스니핏에 불과하다.

조각의 모음을 만들기 위한 템플릿 문서 필요!

---

index.adoc 파일을 생성 

 

⬇

 

Asciidoc 문법으로 템플릿 문서 작성

• 문서의 제목
• 문서 생성자 정보
• API 문서의 목차
• 문서 생성 날짜
• API 문서 스니핏 사용 부분 
• ...

//Asciidoc : Spring Rest Docs 를 통해 생성되는 텍스트 기반 문서 포맷
// = 기술 문서 작성을 위해 설계된 마크업 언어

ex) 
= 커피 주문 애플리케이션
:sectnums:
:toc: left                
:toclevels: 4
:toc-title: Table of Contents
:source-highlighter: prettify

Developer Kim <hello@naver.com> 

v1.0.0, 2022.04.08

***
== MemberController
=== 회원 등록
.curl-request
include::{snippets}/post-member/curl-request.adoc[] //하나의 스니핏

.http-request
include::{snippets}/post-member/http-request.adoc[]

.request-fields
include::{snippets}/post-member/request-fields.adoc[]

.http-response
include::{snippets}/post-member/http-response.adoc[]

.response-fields
include::{snippets}/post-member/response-fields.adoc[]

⬇

 

gradle의 :build 혹은 :bootJar 실행

(index.adoc ➡ index.html 파일로 변환!!)

 

⬇

 

index.html 파일 생성됨,

애플리케이션 실행 후 해당 URL 웹 브라우저에 입력

(http://localhost:8080/docs/index.html)

 

⬇

 

확인 완료!