Swagger로 API 문서화하기

Develop

📅 February 25, 2017

•

⏱️2 min read

개발에 있어서 API 문서화는 아주 중요하지만 번거로운 일 중에 하나입니다. 특히 pdf 또는 한글 파일로 관리하고 있다면 갱신할때마다 아주 번거롭습니다.

이를 해결하기 위해 자칭 세계에서 가장 유명한 API 프레임워크인 Swagger 를 사용해보겠습니다. Swagger 공식 홈페이지를 보면 많은 정보가 있습니다.

Swagger UI

Swagger UI를 사용하면 웹 브라우저를 통해 Swagger에 정의된 REST API를 시각화하고 테스트할 수 있습니다. 내장된 테스트 기능을 사용하면 GUI로 API를 테스트하며 결과를 확인할 수 있습니다. 자세한 정보는 GitHub: Swagger UI 를 참고하시면 됩니다.

Swagger Codegen

Swagger Codegen을 사용하면 REST API용 Swagger 문서를 통해 다양한 언어로 SDK를 생성할 수 있습니다. 생성된 SDK를 사용하여 API를 완전히 구현하기 전에 생성된 샘플 서버 구현에서 실시간으로 API를 테스트할 수 있습니다. 자세한 정보는 GitHub: Swagger Codegen 를 참조하시면 됩니다.

Swagger Editor

editor.swagger.io 에서 Swagger Editor, Swagger UI 및 Swagger Codegen을 제공합니다. 최대한 간편한 용도로 사용하시겠다면 yaml 이나 json 파일을 이곳에 import 해서 사용하셔도 됩니다.

이외에도 http://bigstickcarpet.com/swagger-parser/www/index.html Swagger Validator와 Parser가 있습니다.

Docker로 Swagger UI를 적용해보자

앞서 설명하자면 Docker로 실행하는 이유는 "아직 맥북에 npm 환경구축이 안되어서" 입니다. npm install 을 통해 빌드하셔도 됩니다.

1.

먼저 로컬에 Swagger UI GitHub 저장소를 clone 해줍니다.

2.

그 다음 Docker를 실행하고 아래의 명령어를 통해 Dockerfile을 빌드합니다. localhost:80 에 접속하면 Swagger-UI가 실행된 것을 볼 수 있습니다.

docker build -t swagger-ui-builder .
docker run -p 80:8080 swagger-ui-builder

3.

이제 Swagger Editor로 문서를 작성하고 yaml 형식으로 다운로드 받고, 파일을 Swagger/dist/로 이동합니다. 그리고 Swagger/dist/index.html 파일의 url을 swagger.yaml로 수정합니다.

$(function () {
   var url = window.location.search.match(/url=([^&]+)/);
   if (url && url.length > 1) {
     url = decodeURIComponent(url[1]);
   } else {
     url = "swagger.yaml";
   }

이제 웹 서버에 올리기만 하면 API 문서를 쉽게 확인할 수 있습니다!

← Prev Next →