📦 ETC
[Swagger] API 명세도구를 사용해보자
1HOON
2020. 10. 31. 14:39
왜 쓰게 됬나면...
사이드 프로젝트로 MSA 프로젝트를 하고있는데, API 명세가 확실하게 되어있지 않아 아래의 문제점이 발생했다.
- 내가 구현한 API가 정말 RESTful 한지 알 수 없었다.
- 클라이언트 프로젝트에서 요청을 보내야할 API를 찾기위해 관련 프로젝트를 모두 열어 확인해야했다.
- Rabbit MQ를 이용해 프로세스간 통신을 구현해야 하는데, 설계에 대한 내용이 없어 프로세스간 통신을 설계하기가 힘들 것 같았다.
그래서 각 어플리케이션별 구현한 API를 취합해 엑셀로 정리를 해봤다.
그런데 여기서 또 문제가 발생했는데
- 일일이 엑셀 파일에 구현 내용이나 설계 내용을 입력해야했다.
- 그래서 매우 귀찮았다.
- 그런데 엑셀 파일이 없어지면 이 수고로움이 헛수고가 됬다.
- 그리고 세련되지 않은 방법이었다.
그래서 저 엑셀 파일은 과감히 삭제했고, Swagger 라는 도구를 찾게되었다.
Swagger 란
Swagger 는 API를 설계하고 문서화 및 테스팅이 가능한 프레임워크이며, 무료 버전과 상용 버전 모두 존재한다.
Swagger 에는 아래 5개 기능이 포함되어있으며, 여기서 확인할 수 있다.
- API 디자인(설계)
- API 빌드
- API 문서화
- API 테스트
- API 표준화
그리고 오픈 소스로 공개되어있는 툴은 3가지인데, 아래와 같다.
- Swagger Codegen : 서버와 클라이언트에 설계된 API 코드를 생성하는 툴
- Swagger Editor : API를 설계 및 문서화하는 툴
- Swagger UI : 설계된 API를 HTML 페이지로 확인할 수 있는 툴
설치하기
- Swagger Editor 홈페이지에 접속한다.
- Download Swagger Editor 버튼을 클릭하면, 기본 버전(Swagger Editor)과 클라우드 버전(Swagger Hub)을 비교하는 페이지로 이동되는데, 기본 버전의 Download 버튼을 클릭하자.
- 그러면 swagger-editor 깃허브로 이동되는데, 거기서 Docker 항목을 보자. 바로가기
- Docker Hub 에서 이미지를 내려받고 로컬로 Swagger Editor를 사용할 것이므로, Running the image from DockerHub 항목의 명령어를 따라하면 된다.
- docker pull, docker run 명령어까지 수행하고나서 http://localhost 로 접속해보면 아래와 같은 화면이 뜬다.
- 좌측 에디터에서 문법에 맞춰 API 내용을 작성하면 오른쪽 화면에 바로 반영이된다.
하지만, 나는 이미 일부 API를 구현했고 일일이 구현한 내용을 입력하고싶지는 않았다.
구현한 내용을 먼저 불러오고 그 후에 수정을 하든 추가 설계를 하고 싶었다.
그래서 Swagger의 자동화 기능을 사용하는데.... 그 내용은 다음 포스트에!
반응형