[ATDD] 4. 테스트 기반 문서화

목차

1. ATDD + 문서화

2. 문서 자동화

3. Spring Rest Docs 프로세스

4. ATDD + 문서 자동화

 

 

 

 

전체 코드 확인

 

1. ATDD + 문서화

내부 개발자든 외부 파트너든 새로운 사용자를 온보딩하는 데 소요되는 시간을 줄여줄 뿐만 아니라

API에 대한 이해와 활용도를 높이기 위해선 API의 정보를 문서화 하는 작업이 필요하다.

 

ATDD + TDD cycle 로 개발하면서 어느 시점에 문서화 작업을 진행할 수 있을까?

 

개발 전 문서화 장점

• 백엔드 개발자간 병렬 작업
• 백엔드 & 프론트엔드 개발자간 병렬 작업
• 커뮤니케이션 비용을 줄일 수 있음

 

2. 문서 자동화

문서를 코드레벨에서 관리할 수 있도록 하여

문서와 기능에 대한 동기화 작업이 없어지기 때문에 두 개의 관리 포인트를 하나로 줄여준다.

 

Swagger

• Swagger는 API call하여 테스트하는 기능에 특화
• Swagger는 기능이 많은 반면에 Spring Rest Docs는 단순히 문서임
• Swagger 사용 시 불필요한 프로덕션 코드 오염이 발염

 

Spring Rest Docs

• 테스트 코드에 설정(및 작성)하여 프로덕션 코드에 영향이 적음
• Swagger의 api call 기능은 intellij(local)에서 Http Request하는 기능을 사용하여 대체함

 

3. Spring Rest Docs 프로세스

1) Test

컨트롤러 계층에 대한 api 테스트를 작성한다.

테스트 작성 과정에서 문서화에 필요한 요청, 응답 Snippet 정보를 작성해 세팅한다.

 

2) Spring Rest Docs

테스트를 활용해(테스트 실행) 문서화에 사용될 코드 조각(Snippet)을 만든다.

 

3) 문서 템플릿

Adoc 문서 템플릿 파일에 Snipet 들을 가져와 필요한 위치에 include 한다.

 

4) Asciidoctor

Asciidoctor를 실행해 Adoc 파일을 활용하여 html 문서를 만든다.

gradle 설정 등 전체 코드 확인 github

 

4. ATDD + 문서 자동화

 

 

개발 순서

1) 인수 테스트 만들기

2) 컨트롤러(응답하는 부분만) 만들기

3) 응답값이 있는 경우 응답값 생성 로직은 서비스로 위임

4) 위임한 부분(서비스)에 대한 stubbing 하고 문서화 테스트 만들기

5) TDD 로 기능 구현

 

 

 

 

 

 

 

출처

nextstep - ATDD와 함께 클린 API로 가는 길