[1년 후 마실가실] API 문서화 도구

PlayGround/마실가실 리팩토링

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

HJ0216 2024. 10. 10. 18:59

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 실행

🙋‍♀️

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