[API Docs] swagger를 이용한 nodeJS API Document 만들기 2[API Docs] swagger를 이용한 nodeJS API Document 만들기 2

Posted at 2015.05.13 01:15 | Posted in back-end

swagger를 이용한 nodeJS API Document 만들기 2


앞서서 알려드린 swagger API Document를 만드는 두가지 방법중 두번째 방법을 이용해서 swagger API Document를 한번 만들어 보겠습니다.


swagger-tool 이용하기



http://swagger.io 에 접속해서 하단에 보면 swagger API Document를 만들어 낼 수 있는 여러 방법들을 확인할 수 있습니다.

swagger.io 하단페이지
swagger.io 하단페이지

  1. swagger-ui : swagger-ui는 API에 대한 정보를 json 객체로 정의하고 generate하여 API문서를 만드는 형식입니다. 만들어진 API문서에 대한 view영역을 customize 하거나 swagger-ui를 별도의 방식으로 포팅하고 싶다면 해당 방법을 이용해 구축하는 것을 추천 합니다.
  2. swagger-editor : swagger-editor는 swagger api document를 제작할 수 있는 tool 입니다. github에 오픈소스로 공개되어있으며 다운받아 손쉽게 설치할 수 있도록 되어있습니다. 기본적인 swagger-ui view에 API 내용만 변경하여 사용하고 싶다면 해당 방법을 이용하는 것을 추천 합니다.

swagger-ui



swagger-ui build

swagger.io 페이지에서 swagger-ui를 클릭하면 swagger-ui github 페이지로 이동합니다.

github페이지 아래에도 나와있지만, 해당 프로젝트를 빌드하는 방법을 간략하게 설명하면 아래와 같습니다.


  1. npm install
  2. gulp (gulp가 설치되어있지 않다면, npm install -g gulp 로 gulp 설치)
  3. ./dist/ 디렉토리를 확인해보면 빌드된 결과물을 확인할 수 있습니다.

swagger-ui customizing


swaager-ui를 직접 수정해서 view를 바꿔주고 싶으신 분들은 swagger-ui 디렉터리의 src 디렉토리를 수정하면됩니다.


  1. src/main/template : handlebars 를 기본으로하는 template 파일
  2. src/main/html : html,css,image 리소스 파일
  3. src/main/javascript : javascript 파일

swagger-ui 데이터 수정


데이터만 조작하고 싶다면 test/specs/v1.2/petstore/pet.json 파일과 같이 API 관련 json 파일을 만들어줍니다.

test/specs/v1.2/petstore/api-docs.json 파일의 apis 관련 내용을 만들어준 json 파일로 대체 합니다.


"apis": [
    {
      "path": "http://localhost:8081/v1.2/petstore/pet.json",
      "description": "Operations about pets"
    },
    {
      "path": "http://localhost:8081/v1.2/petstore/user.json",
      "description": "Operations about user"
    },
    {
      "path": "http://localhost:8081/v1.2/petstore/store.json",
      "description": "Operations about store"
    }
  ],

이후 위에 설명한 방법대로 빌드하면 됩니다.

swagger-ui를 이용해서 API Document를 만들 경우 단독적인 swagger 페이지가 아니라 다른 웹 페이지에 함께 들어가야하는 경우 유용합니다.


swagger-editor



swagger-editor build


swagger.io에서 swaged-editor 를 클릭하거나 아래의 ‘source’를 클릭할 경우 github페이지로 이동합니다.

github페이지에도 나와있지만 해당 프로젝트를 빌드하는 방법은 간단합니다.

npm start

명령어로 설치 및 로컬서버 호스팅까지 grunt기반으로 완성해 줍니다. (swagger-ui는 glup 기반인데, swagger-editor는 grunt 기반 ㅎㄷㄷ;;)


swagger-editor 사용법


swagger-editor 화면
swagger-editor 화면

build하고 나타난 페이지를 보면 알 수 있듯이 기본적으로 tool이 갖춰야할 건 모두 가지고 있습니다.



상단 bar

  1. File : 새로운 문서를 작성하거나, 예제를 불러오거나, JSON파일을 import/export할 수 있는 기능을 수행할 수 있습니다.
  2. Perferences : 화면의 font size 같은 구성요소의 설정을 변경할 수 있습니다.
  3. Generate Server : 화면에서 작성한 json 을 기반으로 원하는 프레임워크에 맞게 api document를 generate 시킬 수 있는 완성된 서버 코드를 다운로드 합니다.
  4. Generate Client : 화면에서 작성한 json을 기반으로 원하는 프레임워크에 맞게 api document의 클라이언트 코드를 다운로드 합니다.
  5. Help : swagger json을 작성하는데 필요한 spec 정보나 홈페이지로 이동할 수 있습니다.

좌측 json 화면

좌측에 보이는 json 객체를 swagger spec에 맞춰 작성하면 우측에 결과화면을 보여줍니다.


우측 API 화면

좌측의 json 객체에 정의된 API의 내용을 좀 더 visual하게 보여줍니다. 코드 생성시 보여지는 화면과는 거리가 있습니다.



정리하면..


정리하면 기존에 존재하는 API들에 대해서 swagger Document를 정리하기 위해서는 swagger-ui, swagger-eitor 두가지 중 하나를 선택해서 작성할 수 있습니다.


swagger-ui는 view화면까지 모두 수정하여 다른 페이지내에 하나의 탭으로 존재해야하는 경우 유용하고


swagger-editor는 swagger에서 제공하는 기본 ui를 기반으로 데이터만 json 형태로 작성해야하는 경우 유용합니다.


개인적으로 swagger-editor를 이용해서 작성하고 generate server를 이용해서 nodeJS 기반의 swagger generator server 코드를 다운받아 사용했습니다.


별도로 클라이언트를 만들지 않고도 다운받은 서버를 실행시키고 접속하면 swagger document가 완성되어 있습니다.


swagger API를 구성하기 위해서는 swagger spec에 맞춰서 이용해야합니다.


다음에는 swagger spec에서 필요한 부분들만 이야기해보겠습니다.

Name __

Password __

Link (Your Website)

Comment

SECRET | 비밀글로 남기기