[NodeJS] Swagger 3.0 설정

오늘은 API 개발에서 유용하게 활용할 수 있는 GUI 라이브러리 하나를 소개하려고 한다. Swagger라는 오픈 소스 라이브러리로 HTML 화면에서 API의 URL을 직접 보고 테스트할 때 사용할 수 있는 개발 툴이다.

 

이번 포스트에서 Swagger란 무엇인지 알아보고, 설치 및 설정, 마지막 사용 방법까지 내용을 공유할 것이다. 들어가기 앞서 이후 가이드는 NodeJS 환경에서 작성되었고, 라이브러리 3.0 버전을 기준을 했음을 밝힌다. (Swagger는 2.x 버전과 3.x 버전 두 개가 있다.)

 

Swagger 란

Swagger는 HTML 환경에서 REST API의 설계부터 구성, 테스트, 문서화를 가능하게하는 오픈 소스 라이브러리다. 프론트가 아직 만들어지지 않았거나, API 로직을 체계적으로 관리하고 싶을 때 유용하게 사용될 수 있다. QA 차원에서 전체적인 기능 테스트를 진행할 때 사용해도 좋다.

이 라이브러리를 통해 구현된 GUI 화면에서 개발자는 API 리소스를 시각화하고 Postman 을 사용하는 것처럼 서버와 상호작용할 수 있다.

 

Swagger 구현 화면

아래 이미지는 직접 작업한 NFT 관련 API의 Swagger 구현 화면이다. REST 환경에서 작업한 API 리스트가 잘 구분되어 있음을 확인할 수 있다.

 

GET, POST 등 대분류 카테고리는 Swagger 설정에서 그룹화시켜놓은 값이다. 각 리스트에는 API 호출 주소 URL값과 Method 등이 표기되고, 필요하다면 아래와 같이 API에 대한 상세 설명을 달아줄 수 있다.

 

 

Swagger 설치

NodeJS 기준에서 Swagger 설치는 한 줄의 커멘드라인 명령어로 끝낼 수 있다. 패키지 매니저(NPM)로 swagger-jsdoc과 swagger-ui-express 라이브러리를 다운받으면된다.

 

여기서 swagger-jsdoc 라이브러리는 JavaScript 환경에서 Swagger 설정을 문서처럼 작성할 수 있게끔 도와준다. 코드에 주석을 달듯 어노테이션(Annotation)을 통해 코드와 Swagger를 연결시켜준다.

 

swagger-ui-express 라이브러리는 Express 프레임워크가 관리하는 REST API 주소들을 UI 측면에서 시각화하는 유틸리티 모듈이다. 개발자는 swagger-jsdoc으로 구성한 설정을 이 라이브러리를 통해 실제 HTML 화면으로 구현할 수 있다.

 

--save-dev 플래그를 추가하는 이유는 packege.json 파일의 devDependencies에만 라이브러리를 추가하기 위함이다. 상용 단계에서 Swagger를 사용할 일이 없고 개발 단계에서만 필요하기 때문이다.

 

# swagger-jsdoc, swagger-ui-express 설치 (devDependencies 추가)
npm i swagger-jsdoc swagger-ui-express --save-dev

 

Swagger 설정

본격적인 설정 방법을 소개하기 전에 프로젝트 내부 구조를 공유한다. 설정에 필요한 포인트는 총 3 개로 아래 이미지를 참고하여 파악해두자.

 

Swagger 설정 파일

• app.js
• swagger.js (/utils 경로에 지정)
• *.yaml (/utils/swagger 경로에 지정)

 

 

app.js

app.js 에서는 swagger 설정 파일이 export 하는 모듈 2개를 import 한 뒤 express 설정에 추가한다(= app.use("...")). swaggerUi는 Express 프레임워크에 개발자가 설정한 Swagger의 UI를 추가하며, specs 오브젝트는 Swagger의 옵션 값을 포함하고 있다.

 

//* Swagger
const { swaggerUi, specs } = require("./utils/swagger");
app.use("/api-docs", swaggerUi.serve, swaggerUi.setup(specs));

 

swagger.js

이 파일은 온전히 Swagger 옵션값 설정에 사용된다. 어떤 버전으로 실행할 지부터 호스트와 서버 그룹 정보 등에 대한 메타 데이터를 저장한다. 아래 소스는 가장 기본적인 옵션 값들을 추려낸 것이다. 필요에 따라 공식문서를 참고해 수정할 수 있다.

 

• openapi : Swagger 버전을 명시한다. 크게 2.x 버전과 3.x 버전이 있으며, 사용법에 차이가 있다.
• info : 해당 프로젝트의 메타데이터를 기재한다.
• host : HTML 화면이 출력될 ip, port를 기입한다. (swagger 뷰는 이 ip, port 뒤 /api-docs 주소로 접근할 수 있다.)
• basePath : REST API를 주소로 분류할 때 베이스가 되는 경로를 기입한다.
• servers : API 목록을 그룹화하여 관리할 수 있게 설정하는 란이다.
• apis : swagger가 적용될 router 및 스키마 관련 ymal 파일을 읽어올 때 참조 경로다.

위 옵션에 대한 설정이 되었다면, 해당 옵션 오브젝트를 swagger-jsdoc의 함수형 모듈에 담아 export 하면 된다. 총 export 항목은 swagger-ui-express과 옵션이 설정된 swagger-jsdoc 모듈들이다.

 

const swaggerUi = require("swagger-ui-express");
const swaggerJsdoc = require("swagger-jsdoc");

const options = {
  swaggerDefinition: {
    openapi: "3.0.0",
    info: {
      title: "NFT API",
      version: "1.0.0",
      description: "NFT Token API on NodeJS",
    },
    host: "localhost:3000",
    basePath: "/",
    servers: [
      {
        url: "http://localhost:3000/node",
      },
    ],
  },
  apis: ["./routes/*.js", "./utils/swagger/*"],
};

const specs = swaggerJsdoc(options);

module.exports = {
  swaggerUi,
  specs,
};

 

*.yaml 파일

이 파일은 swagger HTML 화면에서 포맷으로 표현될 데이터에 대한 스키마 옵션을 정의한다. 예를 들어, request나 response에 예시로 출력될 데이터 스키마를 지정할 수 있다. 자세한 화면은 이 글 마지막 Swagger 사용 부분에 이미지 캡처로 참고할 수 있다.

 

조금 더 다양한 예시를 원한다면 Swagger 공식 에디터 링크를 참조하면 도움이 될 것이다.

 

yaml 파일 스키마 목록

• componnents
• securitySchemes
• requestBodies
• responses
• headers
• examples
• links
• callbacks

 

# components
components:
  # 재사용 스키마 포멧 (data models)
  schemas:
    # tokenInfo
    tokenInfo:
      type: object
      properties:
        name:
          type: string
          description: "토큰 이름(Name)"
          example: "Coin"
        symbol:
          type: string
          description: "토큰 심볼(Symbol)"
          example: "SYMBOL"
    ...

    # approve
    approve:
      type: object
      properties:
        sender:
          type: string
          description: "요청자(msg.sender)"
          example: "0xAb78d42f2C659B5bDeff87FdB227c150"
        privateKey:
          type: string
          description: "개인키(Private Key)"
          example: "0x2d5af7250fb0ea8070efaf271954336c5cdf0029754ba156"
        approveAddress:
          type: string
          description: "토큰 권한 허용 주소"
          example: "0xfe2e704dFbD6015536f462049588e9e8"
        tokenId:
          type: string
          description: "토큰 ID"
          example: "123"

     ...

  # 보안 스미카 정의(Authentication. Ex, JWT 토큰)
  # securitySchemes:
  #   ...

  # 재사용 Request Bodies
  # requestBodies:
  #   ...

  # 재사용 Responses (Ex, HTTP 코드 -> 200, 401, 400)
  # responses:
  #   ...

  # 재사용 Response Headers
  # headers:
  #   ...

  # 재사용 Examples 포멧
  # examples:
  #   ...

  # 재사용 Links
  # links:
  #   ...

  # 재사용 Callbacks
  # callbacks:
  #   ...

 

Swagger 사용

성공적으로 swagger가 적용되었다면 애플리케이션이 실행되었을 때, /api-docs 경로로 아래와 같은 HTML 화면이 구현되는 것을 확인할 수 있다.

 

이 참고 이미지는 실제로 /tokenInfo라는 API에 request를 보내 관련 response가 어떻게 반환되는지를 보여주고 있다. 설정에 따라 request parameter 혹은 body 등을 활용해서 인자값을 지정할 수 있고, HTTP status 값에 따라 반환되는 response를 화면으로 직접 확인할 수 있다.