[Swagger] API 명세도구를 사용해보자

왜 쓰게 됬나면...

---

사이드 프로젝트로 MSA 프로젝트를 하고있는데, API 명세가 확실하게 되어있지 않아 아래의 문제점이 발생했다.

 

1. 내가 구현한 API가 정말 RESTful 한지 알 수 없었다.
2. 클라이언트 프로젝트에서 요청을 보내야할 API를 찾기위해 관련 프로젝트를 모두 열어 확인해야했다.
3. Rabbit MQ를 이용해 프로세스간 통신을 구현해야 하는데, 설계에 대한 내용이 없어 프로세스간 통신을 설계하기가 힘들 것 같았다.

 

그래서 각 어플리케이션별 구현한 API를 취합해 엑셀로 정리를 해봤다.

 

 

그런데 여기서 또 문제가 발생했는데

 

1. 일일이 엑셀 파일에 구현 내용이나 설계 내용을 입력해야했다.
2. 그래서 매우 귀찮았다.
3. 그런데 엑셀 파일이 없어지면 이 수고로움이 헛수고가 됬다.
4. 그리고 세련되지 않은 방법이었다.

 

그래서 저 엑셀 파일은 과감히 삭제했고, Swagger 라는 도구를 찾게되었다.

 

 

Swagger 란

---

Swagger 는 API를 설계하고 문서화 및 테스팅이 가능한 프레임워크이며, 무료 버전과 상용 버전 모두 존재한다.

 

Swagger 에는 아래 5개 기능이 포함되어있으며, 여기서 확인할 수 있다.

 

• API 디자인(설계)
• API 빌드
• API 문서화
• API 테스트
• API 표준화

 

그리고 오픈 소스로 공개되어있는 툴은 3가지인데, 아래와 같다.

 

• Swagger Codegen : 서버와 클라이언트에 설계된 API 코드를 생성하는 툴
• Swagger Editor : API를 설계 및 문서화하는 툴
• Swagger UI : 설계된 API를 HTML 페이지로 확인할 수 있는 툴

 

 

설치하기

---

1. Swagger Editor 홈페이지에 접속한다.
2. Download Swagger Editor 버튼을 클릭하면, 기본 버전(Swagger Editor)과 클라우드 버전(Swagger Hub)을 비교하는 페이지로 이동되는데, 기본 버전의 Download 버튼을 클릭하자.
3. 그러면 swagger-editor 깃허브로 이동되는데, 거기서 Docker 항목을 보자. 바로가기
4. Docker Hub 에서 이미지를 내려받고 로컬로 Swagger Editor를 사용할 것이므로, Running the image from DockerHub 항목의 명령어를 따라하면 된다.
5. docker pull, docker run 명령어까지 수행하고나서 http://localhost 로 접속해보면 아래와 같은 화면이 뜬다.
6. 좌측 에디터에서 문법에 맞춰 API 내용을 작성하면 오른쪽 화면에 바로 반영이된다.

 

하지만, 나는 이미 일부 API를 구현했고 일일이 구현한 내용을 입력하고싶지는 않았다.

구현한 내용을 먼저 불러오고 그 후에 수정을 하든 추가 설계를 하고 싶었다.

 

그래서 Swagger의 자동화 기능을 사용하는데.... 그 내용은 다음 포스트에!