Spring MVC - API 문서화

API 문서화란?

클라이언트가 REST API 백엔드 애플리케이션에 요청을 전송하기 위해 알아야 되는 요청 정보를 문서로 잘 정리하는 것을 말한다.

요청 정보에는 요청 URL(또는 URI), Request Body, Query Parameter 등이 있다.

 

왜 필요할까?

우리가 만든 REST API 기반의 백엔드 애플리케이션을 클라이언트 쪽에서 사용하기 위해서이다.

우리가 만든 제품을 고객이 사용할 수 있도록 메뉴얼을 만들어주는 것이라고 생각하면 된다.

 

 

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

우리가 만든 애플리케이션의 API들을 모두 수기로 작성하는 것은 매우 힘든 일이다.

(API의 수가 적다면, 충분히 만들만하다고 생각이 될 수도 있다)

 

애플리케이션의 기능은 언제든지 추가될 수 있고, 운영 중에 수정이 될 가능성도 있다.

이런 변경 사항이 생길 때마다, 직접 수기로 작성하는 것은 매우 위험한 일일 것이다.

(몇몇 API들을 빼먹고 문서화 시키는..)

 

API 문서 생성의 자동화를 통해, 우리는 완성도 있는 문서화를 진행할 수 있고, 무엇보다 시간이 크게 단축될 것이다.

 

 

Spring Rest Docs와 Swagger

이 둘은 모두 API 문서를 자동 생성해주는 방식이다.

 

Swagger를 사용하면, 많은 애너테이션들이 애플리케이션 코드에 추가된다. 이는 개발자에게 불편한 구조로 여겨질 수 있고, 기능 구현과는 전혀 관련이 없는 애너테이션이 추가되는 것은 바람직하지 않다.

(그러나 Swagger는 'postman'과 같은 API 요청 툴로써의 기능을 사용할 수 있다는 장점이 존재한다)

 

• Swagger에 대해 더 자세히 알아보고 싶다면
  • https://swagger.io/
  • https://swagger.io/docs/specification/about/

• SpringDoc에 대해 더 자세히 알아보고 싶다면
  • https://springdoc.org/

 

Spring Rest Docs는 Swagger와는 다르게, 애플리케이션 기능 구현과 관련된 코드에는 API 문서 생성을 위한 애너테이션이 추가되지 않는다.

또, 테스트 케이스에서 전송하는 API 문서 정보와 Controller에 요청되는 정보가 하나라도 일치하지 않으면, 테스트 결과가 'failed'가 되면서, API 문서가 생성되지 않는다.

(즉, 테스트 케이스를 통해 결과가 'passed'인 경우만, API 문서가 생성되기 때문에 실제 스펙 정보와 문서 정보가 불일치해서 발생하는 문제를 사전에 예방할 수 있다는 큰 장점이 있다)

 

하지만, Spring Rest Docs는 테스트 케이스를 이용한 문서 생성 방식이기 때문에, 테스트 케이스를 일일이 만들어주고 모두 'passed' 되도록 만들어줘야 된다.

 

 

정리

• API 문서화란 클라이언트가 애플리케이션을 잘 사용할 수 있도록 API를 문서로 잘 정리하는 것을 의미
• API 문서 생성의 자동화가 필요한 이유
  • API 문서를 수기로 직접 작성하는 것은 너무나 비효율적
• Swagger의 API 문서화 방식
  • 애플리케이션 기반의 API 문서화 방식
  • 애플리케이션 코드에 문서화를 위한 애너테이션 포함
  • 가독성 및 유지 보수성 떨어진다는 단점
  • API 툴로써 기능을 활용할 수 있다는 장점
• Spring Rest Docs의 API 문서화 방식
  • 테스트 코드 기반의 API 문서화 방식
  • 애플리케이션 코드에 문서화를 위한 정보 미포함
  • 테스트 케이스를 반드시 작성하고, 결과가 'passed'여야 문서가 생성
  • API 툴로써 기능은 따로 제공되지 않음

 

이제 Spring Rest Docs에 관해 자세히 알아보자.

 

 

Spring Rest Docs의 API 문서 생성의 전체적인 흐름

https://ocblog.tistory.com/57

1. 먼저 테스트 케이스를 작성하고 실행하면, Snippets(.adoc 확장자)라는 문서에 사용할 조각들이 생성된다.
2. Snippets 조각들을 사용자가 의도하는 대로 템플릿에 넣는다.
3. 만들어진 템플릿을 기반으로 Html 파일을 생성한다.

 

Spring Rest Docs 설정

1. builde.gradle 설정

build.gradle 설정

• (1) .adoc 파일 확장자를 가지는 AsciiDoc 문서를 생성해주는 Asciidoctor를 사용하기 위한 플러그인을 추가
• (2) ext 변수의 set() 메서드를 이용해서 API 문서 스니핏이 생성될 경로를 지정
  • ext 변수에 대해
    
    • https://docs.gradle.org/current/userguide/userguide.html
• (3) AsciiDoctor에서 사용되는 의존 그룹을 지정
  :asciidoctor task가 실행되면 내부적으로 (3)에서 지정한 ‘asciidoctorExtensions’라는 그룹을 지정
• (4) spring-restdocs-core와 spring-restdocs-mockmvc 의존 라이브러리가 추가
• (5) spring-restdocs-asciidoctor 의존 라이브러리를 추가
  (3)에서 지정한 asciidoctorExtensions 그룹에 의존 라이브러리가 포함됨
• (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 되며, copy된 index.html 파일은 API 문서를 파일 형태로 외부에 제공하기 위한 용도로 사용할 수 있음
  • (8-1) :asciidoctor task가 실행된 후에 task가 실행 되도록 의존성을 설정
  • (8-2) "build/docs/asciidoc/" 경로에 생성되는 index.html을 copy한 후,
  • (8-3) "src/main/resources/static/docs" 경로로 index.html을 추가
• (9) :build task가 실행되기 전에 :copyDocument task가 먼저 수행 되도록 함
• (10) 애플리케이션 실행 파일이 생성하는 :bootJar task 설정
  • (10-1) :bootJar task 실행 전에 :copyDocument task가 실행 되도록 의존성을 설정
  • (10-2) Asciidoctor 실행으로 생성되는 index.html 파일을 jar 파일 안에 추가
    jar 파일에 index.html을 추가해 줌으로써 웹 브라우저에서 접속(http://localhost:8080/docs/index.html) 후, API 문서를 확인할 수 있음

 

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

build.gradle 설정이 완료되면, API 문서 스니핏이 생성되었을 때, 이 스니핏을 사용해서 최종 API 문서로 만들어 주는 템플릿 문서(index.adoc)를 생성해주어야 한다.

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

 

정리

• Spring Rest Docs의 API 문서 생성 흐름
  • 슬라이스 테스트 코드 작성 →
  • API 스펙 정보 코드 작성 →
  • Test task 실행 →
  • API 문서 스니핏 생성 →
  • 스니핏을 포함한 API 문서 생성
  • .adoc 파일의 API 문서를 HTML로 변환
• Spring Rest Docs를 사용해서 API 문서를 생성하기 위해서는 .adoc 문서 스니핏을 생성해주는 Asciidoctor 필요
• HTML로 변환된 API 문서는 외부에 제공이 가능하고, 웹 브라우저를 통해 확인이 가능