SEB_BE 57일차 - API 문서화

💡오늘의 학습목표

• API 문서화
• Spring Rest Docs

📔 API 문서화

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

📖 Spring Rest Docs vs Swagger

✔ Swagger의 API 문서화 방식

• Controller나 DTO 클래스에도 Swagger의 애너테이션을 일일이 추가해 주어야함
• 장점은 API문서 생성 시 Postman처럼 API 요청 툴로써의 기능을 사용할 수 있음

✔ Spring Rest Docs의 API 문서화 방식

• 슬라이스 테스트를 위한 Controller의 테스트 클래스에 API문서를 위한 정보 추가
• 장점은 테스트 케이스에서 전송하는 API 문서 정보와 Controller에서 구현한 Request Body, Response Body, Query Parameter 등의 정보가 일치하지 않으면 테스트 실행 결과가 실패하면서 API 문서가 정상적으로 생성이 되지 않음
• 애플리케이션에 정의되어 있는 API 스펙 정보와 API문서 정보의 불일치로 인해 발생하는 문제 방지 가능

📔 Spring Rest Docs

• REST API 문서를 자동으로 생성해 주는 Spring 하위 프로젝트

📖 Spring Rest Docs의 API 문서 생성 흐름

1. 테스트 코드 작성
   a. 슬라이스 테스트 코드 작성
   b. API 스펙 정보 코드 작성
2. test 태스크(task) 실행
   a. 작성된 슬라이스 테스트 코드 실행
   b. 테스트 실행 결과가 passed 면 다음 작업 진행, failed면 수정 후 다시 테스트 진행
3. API 문서 스니핏(.adoc 파일) 생성
   a. 테스트 케이스의 테스트 실행 결과가 passed 이면 테스트 코드에 포함된 API 스펙 정보 코드를 기반으로 API 문서 스니핏이 .adoc 확장자를 가진 파일로 생성됨.

   스니핏(snippet)은 일반적으로 코드의 일부 조각. 여기서는 문서의 일부 조각
   스니핏은 테스트 케이스 하나 당 하나의 스니핏이 생성

4. API 문서 생성
   a. 생성된 API문서 스니핏을 모아서 하나의 API문서로 생성
5. API문서를 HTML로 변환
   a. 생성된 API 문서를 HTML파일로 변환
   b. HTML로 변환된 API문서는 HTML 파일 자체를 공유할 수도 있고, URL을 통해 해당 HTML에 접속해서 확인할 수 있다.

📖 Spring Rest Docs 설정

1. build.gradle 설정
2. API문서 스니핏을 사용하기 위한 템플릿 API 문서 생성
   
   

• (1) .adoc 파일 확장자를 가지는 AsciiDoc 문서를 생성해주는 Asciidoctor를 사용하기 위한 플러그인을 추가
• (2) ext 변수의 set() 메서드를 이용해서 API 문서 스니핏이 생성될 경로 지정
• (3) AsciiDoctor에서 사용되는 의존 그룹 지정. asciidoctor task가 실행되면 내부적으로 (3)에서 지정한 asciidoctorExtensions라는 그룹을 지정
• (4) 추가함으로써 spring-restdocs-core와 spring-restdocs-mockmvc 의존 라이브러리가 추가됨.
• (5) spring-restdocs-asciidoctor 의존 라이브러리 추가 (3)에서 지정한 그룹에 의존 라이브러리가 포함됨.
• (6) :test task 실행 시, API 문서 생성 스니핏 디렉토리 경로를 설정
• (7) :asciidoctor task 실행 시, Asciidoctor 기능을 사용하기 위해 :asciidoctor task에 asciidoctorExtensions을 설정
• (8) :build task 실행 전에 실행되는 task :copyDocument task가 수행되면 index.html 파일이 src/main/resources/static/docs 에 copy 되고, 카피된 파일은 API 문서를 파일 형태로 외부에 제공하기 위한 용도로 사용 가능
• (9) 에서는 :build task 가 실행되기 전에 :copyDocument task가 먼저 수행되도록 한다.
• (10) 애플리케이션 실행 파일이 생성하는 :bootJar task 설정
  a. (10-1)에서는 :bootJar task 실행 전에 :copyDocument task가 실행되도록 의존성 설정
  b. (10-2)에서는 Asciidoctor 실행으로 생성되는 index.html 파일을 jar 파일 안에 추가해준다. jar 파일에 index.html을 추가함으로써 웹 브라우저에서 접속(http://localhost:8080/docs/index.html) 후, 문서 확인 가능

  (8)에서 copy되는 index.html은 외부에 제공하기위한 용도
  (10)에서는 html파일을 애플리케이션 실행 파일인 jar파일에 포함해서 웹 브라우저에서 API문서를 확인하기 위한 용도

✔ API 문서 스니핏을 사용하기 위한 템플릿(또는 source파일) 생성

• Gradle 기반 프로젝트에서는 src/docs/asciidoc/ 에 해당하는 디렉토리 생성
• 디렉토리 내에 비어있는 템플릿 문서index.adoc 생성