[라이브러리] Swagger & REST API

Swagger가 나온 배경

협업을 위해 필요한 라이브러리

서버 개발자B가 클라이언트 개발자A에게 API 스펙이 담긴 문서를 전달해줍니다.

일반적으로는 엑셀이나 워드 등으로 API 스펙을 작성해서 보내줬습니다.

그럼 그 스펙 문서를 다시 수정해서 보내줘야되는 그런 귀찮은 부분들이 존재했습니다.

이런 문제와 더불어 수작업으로 진행되다 보니 오류 사항도 있었습니다.

그래서 이런 문제들을 해결하고자 해서 나온 라이브러리가 Swagger입니다.

Swagger란??

서버로 요청되는 API 리스트를 HTML 화면으로 문서화하여 테스트 할 수 있는 라이브러리를 의미합니다.

이 라이브러리는 서버가 가동되면서 @RestController를 읽어 API를 분석하여 HTML 문서를 작성합니다.

위에서 말한 서버로 요청되는 API 리스트는 스프링 부트와 연관되어 있습니다.

Swagger는 스프링 부트뿐만 아니라 여러가지 언어들 클라이언트, 서버 각 곳곳에서 사용되는 언어들 거의 다 사용할 수 있습니다.

Swagger는 서버가 가동되면서 RestController 어노테이션에 붙어있는 클래스들을 읽어서 API를 자동으로 분석하고 HTML 문서로 작성을 해줍니다.

Swagger가 필요한 이유

Rest API의 스펙을 문서화 하는 것은 매우 중요합니다.

API를 변경할 때마다 Reference 문서를 계속 바꿔줘야하는 불편함이 있는데

Swagger를 사용하면 자동으로 내가 어떤 코드를 수정하든 말든 가동할때마다

이 문서를 자동으로 갱신해서 업데이트 해주기 때문에 협업에 있어서 효율적으로 사용할 수 있습니다.

Rest API

Swagger는 Rest API를 관리하기 쉽게 나온 라이브러리입니다.

그렇기 때문에 Swagger를 알려면 Rest API가 뭔지 알아보도록 하겠습니다.

 

REST API는 정보들이 주고 받아지는데 있어서 개발자들 사이에 널리 쓰이는 일종의 형식입니다.

어떤 기술이나 제품이 아니라, 형식이기 때문에 어떤 프로그램을 쓰든 무슨 프레임워크를 쓰든,

소프트웨어를 만들든 이 형식에 맞춰서 기능들을 구현하면 됩니다.

 

먼저 API를 살펴보면 어떤 기계를 만들면, 사용자가 그 기능들을

전부 제어할 수 있도록 제어장치를 만들어야 합니다.

예를 들어 TV는 켜거나 끄고, 채널을 선택하고, 음량을 조절할 수 있게 해줘야 합니다.

그래서 리모컨이 있는거고 같은 이유로 자판기에는 버튼들이 있고 컴퓨터에는 키보드와 마우스가 있습니다.

이런 것들을 ‘인터페이스’ 라고 부릅니다. 즉, 기계와 인간 간의 소통창구입니다.

사용자가 명령을 넣는거 뿐만 아니라 그 결과와 정보들을 받아오기 위한

TV의 스크린, 컴퓨터의 모니터 또한 인터페이스에 속한다고 할 수 있습니다.

 

이제 소프트웨어 영역에서 살펴보면 사용자들이 프로그램이나 사이트, 앱을 원하는데로 제어하고 정보를 볼 수 있도록 버튼, 스크롤바, 슬라이더, 브라우저 창 등의 소프트웨어적인 장치들이 있습니다.

이런 것을 소프트웨어와 인간 간의 소통을 위한 ‘User Interface’라 볼 수 있습니다.

하지만 인간과 소프트웨어 뿐만 아니라

기계와 기계, 소프트웨어와 소프트웨어 사이에도 수 많은 요청과 정보 교환이 이루어지고 있습니다.

이들 사이에도 소통할 수 있는 창구가 필요합니다.

 

소프트웨어가 다른 소프트웨어로부터 지정된 형식으로 요청, 명령을 받을 수 있는 수단을

‘Application Programming Interface’ API 라고 부릅니다.

이 API는 네트워크 뿐만 아니라 웹, OS 등에서도 존재하는 개념입니다.

 

이제 API를 알았으니 REST API에 대해서 알아보도록 하겠습니다.

프론트엔드 웹에서 서버에 데이터를 요청하거나 배달앱에서 서버에 주문을 넣는 등

이런 서비스에서 널리 활용되는 형식이 바로 REST API 입니다.

REST API의 가장 중요한 특성은 각 요청이 어떤 동작이나 정보를 위한 것인지를

그 요청의 모습 자체로 추론이 가능하다는 겁니다.

 

이런 서비스는 개발자 혼자 만드는게 아니라 나중에 인계받을 개발자나 이 API를

활용해 다른 제품을 만들 개발자들은 개발하기 힘들어질 겁니다.

그래서 RESTful 하게 만든 API는 요청을 보내는 주소만으로도 대략 이게 뭘하는

요청이지 파악이 가능합니다.

서버에 REST API로 요청을 보낼때는 HTTP 규약에 따라 신호를 전송합니다.

이 HTTP로 요청을 보낼 때도 여러 메소드가 있는데 REST API 에서는

get, post, delete, put, patch 5가지를 사용합니다.

 

각 요청의 의도를 쉽게 파악할 수 있도록 RESTful 하게 API를 만들기 위해서는

메소드의 목적에 따라 구분해서 사용해야 합니다.

get은 데이터를 Read, 조회하는데 사용합니다.

post는 Create, 새로운 정보를 추가하는데 사용됩니다.

put, patch는 Update, 변경하는데 사용됩니다.

• put은 정보를 통째로 갈아끼울 때
• patch는 정보 중 일부를 특정 방식으로 변경할 때 사용
• delete는 삭제히는데 사용됩니다.

결국 REST API란 HTTP 요청을 보낼때 어떤 URI에 어떤 메소드를 사용할지

개발자들 사이에 널리 지켜지는 약속과 같습니다.