Swagger로 간단한 REST API 명세

Swagger

스웨거(Swagger)는 개발자가  REST 웹서비스를 설계, 빌드, 문서화, 소비하는 일을 도와주는 대형 도구 생태계의 지원을 받는 오픈소스 소프트웨어 프레임워크이다. 대부분의 사용자들은 스웨거 UI 도구를 통해 스웨거를 식별하며 스웨거 툴셋에는 자동화된 문서화, 코드 생성, 테스트 케이스 생성 지원이 포함된다.   

- 위키 -

 

즉, 스웨거는 대표적인 API 관리 도구로 개발한 RESP API 도구를 편리하게 문서화해주며 편리하게 API를 호출하고 테스트 할 수 있는 도구입니다.

 

•  OpenAPI를 구현하기 위한 도구

•  API들이 갖고 있는 명세을 정의할 수 있는 Tool

•  API 사용 방법을 사용자에게 알려주는 문서

 

공식 사이트 : https://swagger.io/

Swagger 기능

1)  API Design (API 설계)

:  Swagger-editor를 통해 api를 문서화하고 빠르게 명세 가능

 

2)  API Development

:  Swagger-codepen을 통해 작성된 문서를 통해 SDK를 생성하여 빌드 프로세스를 간소화할 수 있도록 도와준다.

 

3)  API Documentation

:  Swagger-UI를 통해 작성된 API를 시각화시켜준다.

 

4)  API Testing

:  Swagger-Inspector를 통해 API를 시각화하고 빠른 테스팅을 진행할 수 있다.

 

5)  Standardize

:  Swagger-hub를 통해 개인, 팀원들이 API 정보를 공유하는 Hub

Swagger Hub

•  다양한 프로젝트의 API 관리 기능을 지원해주는 스웨거 서비스입니다. 

•  API Document 역할로 API를 등록하면 해당 API에 대한 작동 테스트가 가능합니다. 

•  여러 명의 개발자가 스웨거 허브에 가입하여 하나의 프로젝트에 대한 API를 작성하고, 테스트 해 볼 수 있습니다.

실습 

구글 검색어 자동완성 API를 테스트 해봅시다.   https://www.google.com

 

Build, Collaborate & Integrate APIs | SwaggerHub

위 swagger hub로 접속해 로그인 후 실습을 진행합니다.

 

1 )  API 생성 ( Create New  →  Create New API )

 

 

 

 

 

1-1 )  API 정보 입력

 

 

2 ) Code Editor에 API 정보 입력

 

1-1)을 완료한 후 기본적으로 생성된 API 정보입니다. 그 아래부터 테스트 하고자하는 API 정보를 입력합니다. 

 

 

3 )  API 정보 입력 후 SAVE 버튼을 눌러 저장합니다.

 

4 )  이후 API 문서를 새로고침하면 테스트 가능한 API가 생성됩니다. 

 

 

5 )  Try it out을 누른 후 query와 client에 값을 넣고 Excute버튼을 누릅니다.

+ 이 때 Client는 일반적인 브라우저 접속 시 정해진 값을 넣어주어야하기 때문에 psy-ab를 입력합니다. 

 

 

6 )  실행하면 다음과 같이 파일 형태로 값이 반환됨을 알 수 있습니다.  

 

 

7 ) 한 번 다운로드 해보면 ABC 입력값에 대한 자동완성 검색어가 유니코드 형태로 주어짐을 확인해볼 수 있습니다. 

 

 

 

이상 간단한 REST API명세서를 작성해보았습니다.

 

 

본 게시물은 '동빈나 Swagger를 활용한 API 명세와 개발 협업 ' YouTube 강의를 듣고 정리한 게시물입니다. 

 

강의 및 출처

Swagger를 활용한 API 명세와 개발 협업

출처: https://ndb796.tistory.com/249 [ 안경잡이개발자:티스토리 ]