Swagger를 이용해보자! 2편

오늘의 주제

지난글에 이어 오늘은 "Swagger-UI를 통한 시각화 및 문서화"와 "Swagger-Codegen을 이용한 프로토타입 코드만들기" 사실 생각보다 Swagger를 통해 할 수 있는 일들이 많은거 같은데, 한글 레퍼런스보다는 영어 레퍼런스 위주로 작성되있기 때문에 한글자 한글자 적는게 너무 어렵네요. 부족한 정보는 다른분들의 글도 참고하시면 될 것 같습니다!

Swagger-codegen

Swagger.io에서 설명하는 Swagger Codegen에 대한 내용입니다.

Swagger를 통해 API Server-stub을 제작할 수 있고 Client SDK를 생성하여 생산속도를 늘릴 수 있다는 내용입니다.

Swagger Codegen에서는 다양한 언어를 지원합니다.( *모든언어를 지원하진 않습니다) Swagger-Codegen에서 제공하는 언어는 다음과 같습니다. 저는 node.js를 이용하여 개발을 하기 때문에 Swagger를 택하여 이용하고 있습니다.

이제 뭐하는 친구인지, 나에게 알맞은 프로그램인지 알아보았으니 직접 설치를 하고 이용을 해보도록 하겠습니다.

지난시간에 작성한  API 디자인을 Swagger-Editor를 통해 다시 열어 줍니다.

Swagger-editor상단을 확인해보면 여러가지 메뉴를 확인할 수 있습니다.

File-> Save as YAML -> .yaml 파일 생성하기를 진행합니다.

사실 Generate Server 메뉴를 통해 아주 간단하게 Swagger-codegen을 이용할 수 있지만 해당 기능(codegenerator)만 이용하시는 분들도 있을꺼라 생각하여 프로그램을 설치하고 실행하는 방법을 통해 진행해 보도록 하겠습니다.

Swagger-codegen Github 주소 입니다 : 여기욧!

리드미를 읽어보시면 다양한 설치 방법이 나와있습니다.

저는 맥사용자 이기 때문에 Homebrew를 통해 간단하게 설치하였습니다.

각자 이용 환경에 맞는 설정을 진행해 주세요.

어려움이 있으신 분들은 그냥 Swagger-editor에 있는 codegen을 통해 진행하셔도 무방합니다.

swagger-codegen generate -i {파일 이름} -l {언어}

깔끔하게 보기 위해 해당경로에서 명령어를 실행해 보도록 하겠습니다.

이렇게 swagger-codegen 명령어를 통해 server stub을 생성할 수 있습니다.

기본적으로 MVC 패턴에 맞춰서 프로토타입이 생성되는 것을 확인할 수 있습니다.

npm install을 통해 Dependency를 모두 맞춰주고 파일을 실행해 봅시다.

기본적으로 Swagger-codegen을 실행하는 과정을 통해 Swagger-UI도 같이 설치되는것을 확인하였습니다.

기존의 프로젝트에 Swgger-Editor 혹은 Swagger-UI를 설치하는 경우 npm에 있는 패키지를 사용하여 설치할 수 있습니다.

명시되어 있는것 처럼 해당주소(localhost:3000/docs)로 접근을 하게되면 

Swagger-ui페이지로 이동할 수 있습니다.

Swagger-UI

Swagger-UI는 에디터를 사용하는 과정에서도 확인할 수 있습니다. 네! 오른쪽에 있던 그 화면입니다.

하지만 다른 분들이 항상 에디터를 켜서 API를 확인할 필요는 없잖아요..? 그쵸?

그래서 독립적인 UI를 가진 페이지를 실행시킬 수 있습니다. Spec에 대해 확인이 가능하고 제작한 API에 대해 TEST도 진행할 수 있습니다. 사용법은 간단히 페이지에 접속하여 만지작 거리다보면 충분히 다 파악하실 수 있을 꺼라 생각합니다.

제작을 완료하면 이렇게 예쁜 UI로 구성된 페이지가 나타나게 됩니다

이렇게 Swagger를 이용하자 2편이 마무리 되었습니다.

사실 2편에서는 별다른 내용은 없고 정말 실행시켜보고 확인하는 과정이 주로 이루어졌는데

(1편에서도 별거 없긴했죠..?) Swagger에 대해서 능숙하게 다룰수 있는 상태는 아니지만 차근차근 구조와 사용법을 익혀간다면 효율 100%의 Swagger를 이용할 수 있을꺼라 생각합니다. 해당 포스팅은 처음해보는 과정을 통해 고통받은 제가 다른분들에게 조금이나마 도움이 될 수 있는 자료를 만들고 싶어서 작성하게 되었습니다. 감사합니다!

샘플코드주소 : https://github.com/Dongineer/swagger-example