Channel API 개발 (2) — Spring Rest API 문서화(Redoc & Swagger)
안녕하세요 프립 백엔드 개발자 김준성입니다.
지난 글에서 Channel API의 역할과 DB 동기화하는 내용을 정리했었는데요.
이번에는 Channel API를 문서화 했던 내용을 정리해보고자 합니다.
아마 Spring 문서화 기술로 Spring Rest Docs 혹은 Swagger는 익숙하고 사용해보신 분들도 많으실 겁니다.
저는 Spring에서 아직 많은 분들이 사용하고 있지 않은 방식과 조합으로 문서화를 했는데요. 최종으로 API를 문서화한 방법은 다음과 같습니다.
FCA 최종 API 문서화 방법
restdocs-api-spec 라이브러리를 사용하여
Redoc + Swagger + Notion으로 API 문서를 만들었습니다.
왜 이런 조합을 선택하게 되었는지와 적용하는 방법 그리고 몇 가지 사용 Tip을 말씀드리고자 합니다.
검색 결과
Google에 spring rest docs, spring redoc, restdocs-api-spec을 검색해보면 각 검색 결과의 수가 26,700,000개 // 46,200개 // 27,800개입니다.
아직까지 spring redoc, restdocs-api-spec의 기술 자료가 많이 부족한 상태인걸 알 수 있습니다. 특히나 Spring에서 redoc을 적용하는 자료는 현시점에서거의 없다고 봐도 무방합니다.
기술 선택 방향성
먼저 많이들 사용하시는 Spring Rest docs와 Swagger의 차이점을 간단하게 설명드리겠습니다.
Spring rest docs의 장단점
[장점]
- 성공한 테스트 코드를 기반으로 문서를 만들 수 있다.
- 프로덕션 코드에 영향을 미치지 않는다.
- Swagger보다 문서의 가독성이 좋다
[단점]
- 테스트 코드가 필수적으로 필요하다
- AsciiDoc이라는 생소한 기술로 문서를 만들어야 한다.
Swagger의 장단점
[장점]
- 어노테이션 혹은 라이브러리를 사용하여 쉽게 만들 수 있다.
- 클라이언트가 실제 요청 & 응답을 테스트할 수 있다.
[단점]
- 서비스 코드에 어노테이션이 들어가야 한다.
- 문서로 보기에는 가독성이 좋지 않다.
처음 문서를 만들기 위해 자료를 찾아보았을 때의 생각은
‘보통 둘 중 한 개를 선택해서 만드는구나. 어떤 기술을 선택하지?’ 였었는데요. restdocs-api-spec 라이브러리가 이 고민을 해소시켜주었습니다.
restdocs-api-spec
해당 라이브러리는 전반적으로 Spring rest docs와 사용법은 거의 흡사하나 테스트 성공 결과 파일이 다른 형태로 저장됩니다. 이 결과 파일이 중요합니다.
[결과 파일]
Spring Rest docs : .adoc 파일
restdocs-api-spec : OpenAPI Specification (OAS)의 형식의 .yaml 또는 .json 파일
Spring rest docs의 경우 snippet 형태로 출력된 .adoc 파일의 문서를 자신이 원하는 구조로 보여줄 수 있도록 가공하는 작업이 필요합니다.
OAS의 형식은 이미 Restful API의 대한 정의를 내리는 표준 형식이기 때문에 이 파일만 있으면 Restful API를 출력할 수 있는 다양한 곳에 적용이 가능하게 됩니다. (Swagger, Postman, Redoc 등)
그래서 최근에는 restdocs-api-spec를 이용하여 서비스 코드에 영향을 가지 않게 테스트를 진행하고 OAS 파일을 이용해 Swagger로 보여주는 자료들도 종종 볼 수 있었습니다.
기존에 Spring rest docs가 가졌던 안정성과 Swagger의 테스트가 가능한 환경을 모두 제공할 수 있게 한 것이죠.
하지만 Swagger만으론 부족하다!
Channel API는 테스트뿐만 아니라 상품의 대한 설명, 타입 등의 설명도 중요하기 때문에 문서로써의 가독성 또한 매우 중요합니다. 하지만 Swagger로는 그 부분을 채워줄 수 없었죠.
‘그러면 OAS를 사용해서 문서를 멋지게만들어주는 문서 생성 도구는 없을까?’ 라는 결론에 닿았고 관련된 도구들을 찾아보기 시작했습니다.
조사하고 비교해본 뒤 결론적으로 선택한 것이 Redoc입니다!
Redoc
redoc은 오픈 소스이고 결과물을 봤을 때 충분히 가독성이 좋다고 판단되었습니다.
그리고 fastAPI에서는 redoc이 내장되어 있다는 것, Docker와 같은 큰 사이트에서도 사용하는 것을 보고 신뢰성을 얻어 선택할 수 있었습니다.
redoc에 대해 좀 더 알고 싶으신 분들은 아래 링크를 참고해주세요.
redoc github : https://github.com/Redocly/redoc
redoc demo : https://redocly.github.io/redoc/
적용 예제
간단한 Book list를 조회하는 RestAPI 명세서를 만드는 예제 코드를 github에 공유해두었습니다. 아래 링크를 참고해주세요.
Github : https://github.com/WKingDeveloper/spring-oas-docs
[결과 화면 예제]
추가로 말씀드리고 싶은 것들
- restdocs-api-spec는 MockMVC, RestAssured 둘다 사용 가능합니다.
저는 통합 테스트로 진행하기 위해 RestAssured를 사용했습니다. - redoc에서 Response sample을 prettyPrint로 보여주기 위해서는openapi3.yaml 파일의 value: |- 를 value: 로 전체 변경해주면 됩니다.
- 해당 필드가 nullable한 경우 fieldWithPath에 .optional() 을 추가해주면 됩니다.
- document의 identifier를 통해 같은 Endpoint에서 여러 응답 형태를 보여줄 수 있습니다.
- openapi3.yaml에 결과 필드 순서는 랜덤 값으로 적용됩니다.
(이 부분이 아쉽네요 😿)
답변 참고 : https://github.com/ePages-de/restdocs-api-spec/issues/198
마치며
제가 Channel API를 만들면서 겪었던 시행착오들을 기술 블로그로 공유할 수 있어서 좋았습니다. 공유드린 내용이 미숙한 점도 많겠지만 유사한 작업을 하시는 분들에게 도움이 되셨으면 좋겠습니다!
