REST API Framework Swagger 탐방기 1부

REST API Framework Swagger 탐방기 1부

 

현재 MEAN 스택으로 (꽁냥꽁냥) 웹 어플리케이션을 만들고 있었는데요.

어느정도 어플리케이션 규모가 커지다 보니, 사용하는 REST API 양도 꽤 많아 지더군요.

(물론 제가 프로젝트 관리에 소홀했던 탓이 크겠죠 하하)

 

아무래도 매일매일 들여다 보는 프로젝트가 아니다 보니, 작은 기능을 추가하려고 할 때마다.

실제 기능 구현하는 시간보다, 전체 프로젝트 구조를 다시 파악하는데 더 많은 시간을 소모했죠

슬슬 문서화의 중요성이 필요해졌죠

(문서화 넘나 어려운 것, 그리고 넘나 귀찮은 것)

일단, 현재 사용중인 RESTful API 들을 먼저 문서화 해야겠다는 생각이 들었습니다.

(사실 이미 만든 API 못 찾아서 또 만들었던 기억이)

 

 

그런데 대체 문서화를 어떻게 해야 하는 거죠?

그래도 뭔가 표준이 있지 않을까 하는 생각에 구글 성님께 살짝 여쭈어 봤습니다.

양식을 찾아보려고 했는데, 문서화를 자동화 해주는 Tool들이 많은 것 같았습니다.

그 중에서 Swagger를 써보기로 했습니다.

(맨 위에 나오기도 했고, 나름 여기저기 추천하는 것 같네요)

일단 소개 글을 읽어 보았습니다

 

.

번역

Swagger™ 의 목표는 사람이나 컴퓨터가 소스 코드나 문서 또는 네트워크 트래픽 정보에 대한 접근 없이도 서비스의 능력을 이해하거나, 연구할 수 있으며, 각 언어에 맞는 표준 REST API를 정의하는 것입니다. Swagger를 통해 적절히 구현 정의만 된다면, 적은 구현으로도 소비자들이 원격 서비스를 이해하거나 소통할 수 있을 것입니다. 낮은 단계의 프로그래밍을 위해 인터페이스를 정의하는 것 같이, Swagger 는 서비스를 사용하기 위한 추측 작업을 필요 없도록 합니다.

 

(영알못이라 번역이 무슨 게임 나레이션 같네요)

요약해보면, 각 개발 언어별로 지원하면서, REST API 스펙만 명시해 주면 되도록,

아무래도 REST API 작업중 노가다 파트를 대신 해주는 거 같네요.

 

 

번역

하향식 접근법

Swagger Editor를 사용해서 Swagger definition을 생성합니다. 그리고 Swagger Codegen 툴을 사용해서 실제 서버 구현을 생성하도록 합니다. 

상향식 접근법

이니 구현된 REST API가 있는 상태에서 Swagger definition를 생성하고자 할 때는, 위에 소개된 Swagger definition을 이용하여 수동으로 제작해도 되고, 만약 JAX-RS, node.js 등등 특정 프레임워크를 사용하고 있다면, Swagger definition 자동 생성을 통해 만들 수 있습니다.

 

사용자가 개발 단계 중 어떤 단계에 있느냐에 따라, 사용법이 다른 것 같네요.

하향식 방법은 아직 REST API 개발이 전혀 이루어지지 않은 단계에서, 적용하는 방법인데요.

Swagger Editor(편집 툴 같은 거)를 통해서 Swagger definition(API 스펙) 을 정의하고

Swagger Codegen으로 서버 코드 파일을 만드는 거 같네요.

상향식 방법은 이미 REST API 서버 코드를 구현한 상태에서 적용하는 방법을 말하네요

Swagger definition을 통해 document 페이지만 제작하거나,

특정 프레임워크를 사용한다면, Swagger definition도 자동으로 뽑아주는 듯 하네요.

생각나는 대로 적다 보니 글이 정리가 안되네요.

위 내용을 정리해서 도식화 해보았어요.

잠시 쉬고 2부로 돌아오겠습니다.