2021.8.28 TIL : Swagger를 통한 REST API 관리

0. API 명세의 필요성

REST API를 처음 설계해보면서 url에 대해 이렇게 작성하면 되는지 여러 번 물어본 적이 있다. 그러면서 이렇게 작성된 url들이 뭔지 프론트에 어떻게 전달해 줘야 하는지에 대해서는 깊게 고민하지 않고, url을 명료하게 작성하면 대충 뭔지 알지 않을까? 이런 생각들을 했던 것 같다. /blog/create/ 이런 식으로 가면 blog 객체를 post 하는 걸꺼다.. 이런 추측 느낌으로? (이심전심 게임이냐고..)

 

그러나 당연히 프로젝트에서 생성하는 여러 API들에 대해 시간을 단축하고 소통을 제대로 하려면 각 API에 대해서 문서화 해서 전달해 줘야 한다. 매번 개발을 배우면서 느끼지만, 이런 게 필요하다 싶은 것들의 대부분은 사람들이 이미 만들어 놨다. 문서화하는 방법엔 여러가지가 있고, 엑셀이나 스프레드시트를 이용해 정리해서 전달해주는 방법도 있다. 

하지만 엑셀 파일은 깃을 이용해서 관리하기에 편하지도 않고 파일을 계속해서 주고 받아야 한다는 점에서 불편하다. 따라서 API 명세 도구가 사용되는데, 그 중에 하나가 웹 문서 형태로 전달이 가능한 swagger이다. 보통은 프로젝트 기간이 장기적으로 이어지게 되면 소통을 편리하게 하기 위해서 사용된다. Swagger는 백엔드와 프론트엔드 프로그램 사이에서 정확히 어떤 방식으로 데이터를 주고 받을지에 대한 명세가 담긴 문서(API 명세서)의 역할을 해준다. 스웨거를 통해 여러 명의 개발자가 하나의 프로젝트에 대해 API를 작성하고 제대로 작동하는지 확인까지 할 수 있다. 

 

1. OpenAPI란 ?

REST API를 위한 표준 api 명세 규격이다. 특정한 서버 API가 있을 때 요청, 응답 API의 접근 경로를 포함해서 전체 API 명세를 어떻게 하면 되는지 그 방법을 규정하고 있다. 스웨거는 이러한 OpenAPI를 이용해서 REST API를 쉽게 설계하고 기획하도록 해준다. OpenAPI 규격은 YAML 이나 JSON 형태로 작성이 가능하다. YAML 으로 작성된 OpenAPI 3.0 규격은 다음처럼 작성하면 된다. 각각이 무슨 의미를 가지는지는 여기에서 상세 문서로 확인할 수 있다. 

*대문자, 소문자 구분되니 유의하기

responses나 Parameter의 경우, 자신이 필요한 것에 맞게 작성할 수 있다. Parameter에 대해서는 여기에 자세히 나와 있다. response 역시도 커스텀화 할 수 있다. 

 

스웨거는 두 가지 방법으로 사용이 가능한데, 첫 번째는 프로젝트 서버 프로그래밍 언어를 사용해서 종속적인 형태로 이용하는 방법이다. 두 번째는 서버 프로그래밍 언어를 전혀 거치지 않고 스웨거를 별도의 웹 문서로 완전히 독립적으로 이용하는 방법이 있다. 즉, YAML 파일을 직접 작성해서 API를 명세하는 방법이다. 공식 문서에서 다루는 내용들은 YAML 파일을 토대로 다루고 있다. 내가 프로젝트에서 사용하는 방식은 drf-yasg를 이용한 첫 번째 방식이다. 그렇기 때문에 파라미터 설정이나, response 값 설정이 공식 문서에서 나온 내용과는 조금 다른 것 같다. 이 부분도 조금 더 이해하고 나면 다시 작성해봐야 겠다.