들어가기 전에

Web API를 작성한 후, Web API사용자에게 Web API문서를 소개하기 위해선 문서화가 필요합니다.

이번 시간엔 Web API를 문서화할 때 사용되는 스웨거(Swagger)에 대해 알아보도록 하겠습니다.

학습 목표

1. Swagger를 사용하는 이유에 대해 이해합니다.

핵심 개념

• API 문서화

• 스웨거가 제공하는 기능 이해

학습하기

//영상 업로드

1. 스웨거(Swagger)란?

스웨거는 Web API 문서화를 위한 도구입니다.

스웨거 홈페이지(https://swagger.io)에서는 스웨거를 OAS(Open API Specification)이라고 소개하고 있습니다.

말그대로 API들이 가지는 명세(Spec)을 관리하기 위한 프로젝트라고 말할 수 있습니다.

Web API를 수동으로 문서화 하는 것은 굉장히 힘든 작업입니다.

Web API의 스펙이 변경되었을 때 문서 역시 변경이 되야 하는데 이를 유지하는 것이 쉽지가 않습니다.

Swagger를 사용하면 Web API가 수정되더라도 상관 없습니다. 문서가 자동으로 갱신이 되기 때문입니다.

2. 스웨거의 기능

스웨거 홈페이지를 가보면 아래와 같은 기능이 있습니다.

1) API Design

2) API Development

3) API Documentation

4) API Testing

5) API Mocking and Virtualization

6) API Governance

7) API Monitoring

8) OpenAPI & Swagger

Web API를 만드는 개발자와 Web API를 이용하는 개발자가 있다고 생각해 보겠습니다. 

Web API를 이용하는 개발자는 Web API가 만들어질 때까지 기다린다면 작업이 상당히 느려질 수 있을 것입니다.

Web API를 만드는 사람과 Web API를 사용하는 사람 간에 미리 명세를 정의하고 공유할 수 있다면

개발이 상당히 편리해 질 것입니다.

지금 이야기 한 것들을 편하게 해주는 도구 중에 하나가 ‘스웨거’라고 말할 수 있습니다.

3. 스웨거 허브를 이용하여 API를 명세화 하고 테스트하기

스웨거 허브 사이트를 이용하면 Web API를 만들지 않더라도 Web API를 명세화할 수 있습니다. 

또한, Web API를 명세화만 하는게 아니라 간단히 테스트도 할 수 있다는 장점을 가지고 있습니다.

생각해보기

스웨거 허브를 이용해 Web API 명세를 정의할 수 있었습니다.

뺄셈을 수행하는 Web API를 추가하려면 어떻게 해야할까요?

참고 자료