[서비스 제작 Side]RESTful API 문서(#1) 툴 서칭

백엔드 개발자라면 알고 있어야 할 RESTful API 문서 만들기~

처음에는 API문서 만드는 툴로 많이 사용한다는 Swagger만을 시험삼아 적용해 볼 생각이었지만
현재 어떤 툴이 있는지 정도는 알고 넘어가야 하지 않을까 라는 마음으로 가볍게 서칭을 해보고
어노테이션 기반으로 Rest api 문서를 만드는 Swagger를 시험삼아 Spring에 적용해보기로 했다.

검색해보며 괜찮은 툴이 많다는 것을 알게되었다.

 

1. Swagger

https://gngsn.tistory.com/69

Node.js + Swagger, 어렵지 않게 사용하기

- nodeJs로 간단한 POC를 제작할 때, 간단히 사용해보았다.
당시 동료 개발자의 추천으로 사용해보았고, 주석처럼 적으며참 쉽고 간편하다는 느낌을 받았다.
하지만, 내 메인인 Spring에서는 사용해보 본적이 없기 때문에 한 번 적용해보고 싶었다.

그래서 직접 Spring에 붙히는 작업도 시험삼아 해보았다.
api 요청을 하고 결과를 볼 수 있어( try out 기능 ), 프론트 개발자에게 제공하기 매우 편리하다.

 

2. Slate

https://minkukjo.github.io/opensource/2020/10/28/Infra-24/

Slate란 무엇인가 + 사용법

- 검색을 하며 알게 된 오픈소스이다.

UI가 참 예쁘다( API 가이드 문서는 시각적인게 상당히 강점으로 작용한다. 왜냐하면, 문서를 보고 이해도를 높이는 데에 시각적인 부분이 어느정도 중요하기 때문이다. 물론 설명을 기똥차게 쓰는게 더 중요하겠지....)

github에서 소스를 clone 떠서 설치하고 구동시키면 간단히 사용히 가능하다.
위 글에 따르면 설치 후, index.html.md 파일만 수정하면 된다는 것이 매력적이라고 한다.

흠이 있다면? 윈도우에서 사용이 어렵다는데.. 보통 리눅스 서버에 올리는 경우가 많기에 문제 될 부분은 아닌 것 같다.

 

3. Open API for Confluence

https://www.youtube.com/watch?v=88hW82dqq8Y

컨플루엔스에서 API 문서를 만들도록 도와주는 위젯이 있다는 걸 처음 알았다.
Swagger UI 이며, Confluence를 사용하고 있다면, 고려해 볼 만한 방법이다.

 

4. gitBook

오픈소스 기술 기반의 정적 사이트 생성기~
책을 쓰듯이 문서를 웹에 올리기 좋게 만든 기능이고, API 문서, 사용자 매뉴얼, 개발 지식 등을 작성할 때 사용할 수 있다.
이 전에 백엔드 개발 멘토링을 진행할 적에 API 문서를 만들자는 과제에 한 멘티 학생이 gitbook으로 api를 만드는 것을 보았는데, 이걸 계기로 이참에 다시 한번 찾아보았다.

서칭 중 코스콤에서 gitbook으로 api 문서를 사용하는 것을 알았다 정도이다.

---

서칭 해 본 툴 중에 눈에 들어온 툴은 Slate와 Confluence의 openapi 문서화 기능이다.
이 2가지 툴은 다음 사이드 프로젝트 모임 때 공유하려 한다.