Swagger Hub를 이용한 REST API 관리

  스웨거(Swagger)는 대표적인 API 관리 도구입니다. 일반적으로 프로그램을 개발할 때에는 백 엔드 개발자와 프론트 엔드 개발자가 서로 협력하는 형태로 개발을 진행하게 됩니다. 이 때 백 엔드 프로그램과 프론트 엔드 프로그램 사이에서 정확히 어떠한 방식으로 데이터를 구조 받을 지에 대한 명세가 필요할 수 있습니다. 이러한 내용이 담긴 문서를 일반적으로 API 명세서라고 말합니다.

  스웨거 허브는 다양한 프로젝트의 API 관리 기능을 지원해주는 스웨거 서비스입니다. 여러 명의 개발자가 스웨거 허브에 가입하여 하나의 프로젝트에 대한 API를 작성하고, 테스트 해 볼 수 있습니다.

  ▶ 스웨거 허브(Swagger Hub): https://swagger.io/tools/swaggerhub/

  바로 한 번 스웨거 허브에 가입한 뒤에 로그인을 하여 실습을 진행해보도록 하겠습니다. 또한 기본적인 Open API 작성 방법에 대해서도 소개하겠습니다. 일단 바로 사이트에 접속하여 [Sign In]에 들어가 회원가입을 진행하겠습니다.

  스웨거 허브(Swagger Hub)를 이용하시면 됩니다.

  회원가입은 깃 허브(Git Hub)를 이용해서 진행할 수도 있지만, 저는 이메일을 이용해서 회원가입을 진행하겠습니다. 기본적으로 스웨거 허브는 혼자서 개인적인 목적으로 사용할 때는 무료로 이용할 수 있습니다. 다만 팀 규모로 이용할 때는 가격 정책이 적용될 수 있답니다.

 회원가입 이후에 조직(Organization)을 생성하여, 자신의 팀원들을 초대할 수도 있습니다. 저는 단순히 예제만 다루는 목적으로 이용할 것이므로 대충 작성하고 넘어가도록 하겠습니다.

  결과적으로 로그인을 진행하게 되면 새로운 API(New API)를 만들 수 있습니다. 말 그대로 특정한 프로젝트 하나에 대한 API 명세서를 작성할 수 있습니다.

  이후에 API를 생성할 때는 설정을 진행할 수 있습니다. Open API 버전은 현재 2.0이 가장 많이 사용되며, 템플릿(Template)을 정해줄 수 있습니다. 템플릿은 API 명세서를 더 쉽게 작성할 수 있도록 도와주는 것으로, 기본적인 API 명세서 형태를 미리 갖춘 문서를 의미합니다.

  가장 기본적인 예제인 펫 스토어(Pet Store) 예제를 통해 API 템플릿을 구성해보도록 하겠습니다. 말 그대로 애견샵 컨셉의 프로젝트 API 명세서라고 이해하시면 됩니다. 이를 많이 참고하셔서 향후 프로젝트의 API를 구성하시면 효율적이에요.

  프로젝트가 생성되면 바로 다음과 같은 화면을 만날 수 있습니다. 처음 이러한 화면을 만나면 당황스러울 수 있으나 익숙해 지면 정말 효율적인 화면 구성이라는 것을 이해할 수 있어요.

  ▶ 화면의 왼쪽에는 API 내비게이션(Navigation)이 존재합니다.

  ▶ 그리고 중간에는 API 명세서의 에디터(Editor)가 들어가 있습니다. 실질적으로 이 소스코드가 API 명세서의 핵심이라고 할 수 있습니다.

  ▶ 오른쪽에는 실제로 API 명세서의 사용자 입장에서 테스트를 할 수 있는 UI 다큐먼트(UI Docs)가 존재합니다.

  실제로 에디터에 작성되어 있는 소스코드가 UI 다큐먼트에서 어떻게 출력되는지 확인해보도록 하겠습니다. 기본적으로 스웨거 코드를 작성할 때는 특정한 API의 경로에 대해서 명시한 뒤에, HTTP 메소드(Method)에 대해서 명시합니다. 이후에 그 동작 과정에 대해서 적어주면 됩니다.

  ▶ GET 방식: 데이터 조회

  ▶ POST 방식: 새로운 데이터의 삽입 및 수정

  ▶ PUT 방식: 기존 데이터의 수정

  ▶ DELETE 방식: 기존 데이터의 삭제

  아래 예제는 /pet/{petId}라는 경로에 GET 방식 및 POST 방식으로 접근했을 때의 처리 방식에 대해서 보여주고 있습니다.

  실제로 오른쪽의 UI 다큐먼트를 보시면, 다음과 같이 테스트 환경이 구축되어 있는 것을 확인할 수 있습니다. 파라미터(Parameter)를 설정하여 데이터를 전송할 수 있습니다. 데이터를 전송하면 서버는 그에 대한 응답(Response)를 주게 됩니다.

  기본적으로 응답 코드가 200인 경우 정상적으로 데이터를 처리하여 반환했다는 것을 의미합니다.

  실제로 다음과 같이 응답 코드 200과 함께 JSON 형태의 응답(Response) 데이터가 출력된 것을 확인할 수 있습니다. 이처럼 REST API 형태로 데이터를 주고 받을 때는 JSON 형식을 이용한다는 특징이 있습니다.

  또한 스웨거 API에서는 인증(Authorize)에 대한 처리 정보도 관리할 수 있습니다.

  그리고 각 데이터 모델(Model)에 대해서도 정의할 수 있는데요, 일반적으로 데이터베이스에 기록되어 있는 모델 형태를 그대로 가져와 사용합니다. 아래 소스코드에서는 주문(Order) 오브젝트에 대해 정의하고 있습니다.

  이어서 다음과 같이 전체 API에 대한 개요를 작성할 수 있으며, 추가적으로 태그(Tag)를 넣어서 각 API를 분류시킬 수 있습니다. 이러한 구성 덕분에 스웨거(Swagger) API는 단 하나의 소스코드로 하나의 단일 프로젝트에 대한 전체 API를 명세할 수 있는 것입니다.

  또한 작성된 코드를 다운로드(Download)하여 여러 개의 프로그래밍 언어 환경에 붙여넣기 할 수 있습니다. [Export] - [Download API]에 들어가서 원하는 형태로 API를 다운로드 해주세요.

  대표적인 형태인 [JSON Resolved]로 다운로드를 진행하면 다음과 같은 압축 파일이 다운로드 됩니다.