[1년 후 마실가실] API 문서화 도구 - Spring REST Docs

1년 전 진행했던 마실가실 프로젝트를 🛠️리팩토링하며 정리한 내용입니다.

 

 

리팩토링을 Backend 부분만 하고 있다보니, 문득.. 다른 이들이 제 API를 확인할 길이 전혀 없다는 걸 최근에 깨달았습니다..!

 

프론트 연결...까지는 시간이 오래 걸릴 것 같아서, 그간 만들어놓은 API를 문서로라도 남겨두면 좋을 것 같아서 API 문서화 도구를 썼습니다.

 

근래 작업한 내용 중에서 가장 많은 블로그 글을 찾아보았습니다..

 

그렇기에 정리가 꼭 필요하다고 판단되어 글을 작성해봅니다.

 

 

1. API 문서화

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

  * 일반적으로 애플리케이션 빌드를 통해 API 문서를 자동 생성하는 경우가 많음

 

 

2. Spring REST Docs or Swagger

Spring REST Docs

  * 애플리케이션 기능 구현과 관련된 코드에 API 문서 생성을 위한 애노테이션 같은 정보가 추가되지 않음

  * Controller 테스트 코드가 선행되어야 하며, Controller 테스트 클래스에 API 문서를 위한 정보가 추가됨

Swagger

  * Postman처럼 API 요청 툴로써의 기능을 사용할 수 있음

  * 웹 인터페이스를 제공해 사용자와 개발자가 API를 테스트할 수 있는 페이지를 쉽게 확인할 수 있음

 

☺️저는 주석으로 학습한 내용을 코드에 작성하는 편이라 Swagger까지 추가하면 코드가 복잡해질 것 같아 REST Docs를 사용했습니다!  

 

 

3. 환경 설정

build.gradle

🌟 Spring REST Docs에 관련된 정보만 기재되어있습니다.

* MockMvc vs RestAssured

  * MockMvc

    * @SpringBootTest와 함께 사용할수도 있고, @WebMvcTest와 함께 사용할수도 있음

  * RestAssured

    * @SpringBootTest와 함께 사용

    * 어플리케이션이 동작하는 실제 환경과 동일한 환경에서 테스트를 진행하고 싶을 때 RestAssured 를 사용

* implementation or runtimeOnly

  * implementation

    * 컴파일 타임에 안전하게 의존성을 관리할 수 있음

    * 의존성의 클래스를 코드에서 직접 import하여 사용할 수 있음

    * 많은 의존성이 컴파일 타임에 추가되면 빌드 시간이 늘어날 수 있음

  * runtimeOnly

    * 가벼운 빌드와 의존성 충돌을 줄일 수 있음

    * 의존성의 클래스를 코드에서 직접 import하여 사용할 수 없음

    * 런타임 시에만 동작하기 때문에 문제가 늦게 발견될 수 있음

 

WebMvcConfig.java

* static resource에 파일을 url로 접근하기 위한 설정

 

 

4. Test Code 작성

UserControllerTest.java

* @ExtendWith or @AutoConfigureRestDocs

  * @ExtendWith({RestDocumentationExtension.class})

    * Spring REST Docs의 기능을 테스트에 확장하여 API 문서화를 자동으로 할 수 있게 함
    * RestDocumentationContextProvider 객체를 제공하여 MockMvc 설정 시 REST Docs 문서화를 할 수 있게 도와줌
    * 테스트 실행 시 REST Docs 관련 설정을 수동으로 추가할 수 있도록 도와줌

  * @AutoConfigureRestDocs

    * Spring REST Docs를 자동 설정해 문서화를 지원
    * Spring Boot에서 자동으로 REST Docs 설정을 구성하여 MockMvc 객체에 REST Docs 관련 설정을 추가
    * MockMvc 객체 생성 시 REST Docs 설정을 자동으로 추가

 

 

5. .adoc 파일 작성

🌟Gradle 프로젝트의 경우, 템플릿 문서가 위치하는 default 경로: src/docs/asciidoc

* Markdown or Asciidoc

  * Markdown

    * 문서 작성용 마크업 언어(태그를 이용하여 문서나 데이터의 구조를 명시하는 언어 )

  * Asciidoc

    * 문서 작성용 마크업 언어 + include 기능 포함

 

 

6. build 실행

 

 

 

🙋‍♀️

본 포스트는 공부 목적으로 작성하였습니다.
보시는 도중 잘못된 부분이나 개선할 부분이 있다면 댓글로 알려주시면 수정하도록 하겠습니다.

 

📑

참고 자료

https://velog.io/@bagt/API-%EB%AC%B8%EC%84%9C%ED%99%94%EC%99%80-Spring-Rest-Docs

API 문서화와 Spring Rest Docs 사용기

https://hudi.blog/spring-rest-docs/

Spring REST Docs를 사용한 API 문서 자동화

https://helloworld.kurly.com/blog/spring-rest-docs-guide/

내가 만든 API를 널리 알리기 - Spring REST Docs 가이드편

https://jaehun2841.github.io/2019/08/04/2019-08-04-spring-rest-docs/#asciidoctor-plugin-%EC%84%A4%EC%A0%95

Spring Rest Docs를 이용한 API 문서 만들기 | Carrey`s 기술블로그

https://velog.io/@galmegi/build.gradle-asciidoctor-%EC%84%A4%EC%A0%95

build.gradle asciidoctor 설정

https://velog.io/@max9106/Spring-Spring-rest-docs%EB%A5%BC-%EC%9D%B4%EC%9A%A9%ED%95%9C-%EB%AC%B8%EC%84%9C%ED%99%94

[Spring] Spring rest docs 적용기(gradle 7.0.2)

https://jake-seo-dev.tistory.com/87

Spring REST Docs + asciidoctor 로 문서 자동 생성해보기

https://github.com/DeveloperAcademy-POSTECH/MacC-Team-Trying-server

GitHub - DeveloperAcademy-POSTECH/MacC-Team-Trying-server

https://devwriter.tistory.com/28

[Spring REST Docs ✍️] 어렵게만 느껴졌던 REST Docs를 적용해보자! (1)