API Documentation

이스·2020년 5월 24일

REST API를 위한 API description format으로, YAML이나 JSON 형식으로 쓰인다.

잘 정리된 API 명세는 API 개발자 본인과 API를 사용하는 모든 사람에게 도움이 된다.

사용자가 REST API를 쉽게 설계하고, 만들고, 문서화하고, 또 사용하도록 도와주는 오픈소스 소프트웨어 프레임워크다.

Swagger tool 중 하나인 Swagger Editor를 이용해 OpenAPI 기반 API 명세를 작성해 볼 수 있다.

브라우저 기반 에디터로, 변경한 내용이 바로 화면에 반영된다.

위에서 Swagger Editor로 작성한 YAML, JSON 파일을 더 깔끔하고 가독성 좋은 페이지로 렌더링 해준다.

redoc-cli를 이용하여 html 파일을 만들 수 있다.

redoc-cli 설치

npm install -g redoc-cli

html 파일 생성

redoc-cli bundle -o [output filename] [source filename]

redoc-cli를 설치하기 위해서는 일정 버전 이상의 node와 npm이 설치되어 있어야 한다.
node 및 npm 버전 업데이트는 이 글을 참고했다.
remote server에서 html 파일 실행

# python2
python -m SimpleHTTPServer [port]

# python3
python -m http.server [port]