Swagger로 Express 시작하기

Express에서 swagger 프로젝트 사용하는 방법을 소개합니다.

Swagger?

Swagger는 Open Api Specification(OAS)를 위한 프레임워크 입니다. 여러 API를 한번에 관리할 수 있는 프로젝트입니다. 주로 REST 웹 서비스를 설계, 빌드, 문서화할 때 활용합니다.

Swagger 기능 5가지

1. API Design

   Swagger-editor를 통해 api를 문서화하고 빠르게 명세화 할 수 있다.

2. API Developement
   Swagger-codegen을 통해 작성된 문서를 통해 SDK를 생성하여 빌드 프로세스를 간소화 한다.

3. API Document

   Swagger-UI를 통해 작성한 API를 시작화 한다.

4. API Testing

   Swagger-Inspector를 통해 API를 빠른 테스팅을 진행할 수 있다.

5. Standardize

   Swagger-hub를 통해 개인, 팀원들이 API 정보를 공유한다.

swagger 커맨드라인 툴 설치

스웨거 모듈(swagger-node)을 글로벌로 설치한다.

npm install -g swagger

설치가 완료되면 다음 명령어들을 사용할 수 있다..

// 노드 프로젝트 시작
swagger project create
// 스웨거 문서 편집
swagger project edit
// 스웨거 문서 문법 체크
swagger project verify
// 생성한 노드 프로젝트 시작
swagger project start
// 유닛 테스트 실행
swagger project test

Swagger 프로젝트 생성

swagger project create demo
// express 선택 

아래와 같은 폴더 구조로 생성한다.

/demo
  /api
    /controllers
    /helpers
    /mocks
    /swagger
 /config
 /node_modules
 /test
app.js
package.json

API Design

swagger project edit

해당 명령어를 실행하면 swagger-edit 툴을 사용해 api를 디자인할 수 있다.
swagger/swagger.yaml 파일이 자동 저장되는 것을 확인할 수 있다.

** 중간 생략 **
paths:
  /hello:
    # binds a127 app logic to a route
    x-swagger-router-controller: hello_world
    get:
      description: Returns 'Hello' to the caller
      # used as the method name of the controller
      operationId: hello
      parameters:
        - name: name
          in: query
          description: The name of the person to whom to say hello
          required: false
          type: string
** 이하 생략 **

x-swagger-router-controller키에 할당된 값은 controllers 폴더의 자바스크립트 파일명이다. 그리고 operationId키의 값은 이 파일의 메쏘드 명이다. /api/controllers/hello_world.js 파일을 들여다 보면 쉽게 이해할 수 있다.

'use strict';
var util = require('util');

module.exports = {
  hello: hello
};

function hello(req, res) {
  var name = req.swagger.params.name.value || 'stranger';
  var hello = util.format('Hello, %s!', name);
  res.json(hello);
}

Swagger Project 실행

swagger 프로젝트를 실행해본다.

swagger project start

Error
Error initializing middleware

---

이 오류가 난다면 노드 10 모듈과 12 모듈의 차이 때문에 발생하는 거라고 한다.
node_modules/bagpipes/lib/fittingTypes/user.js 해당 경로로 들어가서
var split = err.message.split(path.sep); 부분을
var split = err.message.split('\n')[0].split(path.sep);
이렇게 변경해주면 해결할 수 있다.

브라우저에 접속하면 기본으로 제공해주는 api를 확인해볼 수 있다.

localhost:10010/hello?name=Hamon

Swagger-ui 연동

각자 api에 맞게 작성한 swagger 문서를 시각화한 swagger-ui 툴을 사용하려면 직접 연동시켜줘야 한다.

app.js

var SwaggerUi = require('swagger-tools/middleware/swagger-ui');

SwaggerExpress.create(config, function(err, swaggerExpress) {

  // add swagger-ui (/docs)
  app.use(SwaggerUi(swaggerExpress.runner.swagger));

  // install middleware
  swaggerExpress.register(app);
});

브라우저에서 127.0.0.1:10010/docs 를 열어보면 swagger-ui 를 확인할 수 있다.

API Key 등록

swagger-ui 우측 상단에는 api_key가 있다. 이 텍스트 필드에 api_key를 입력하면 url 파라메터로 추가되여 요청된다. API 접근을 위한 보안 설정인 셈이다.
app.js파일에서 SwaggerExpress의 config 객체에 swaggerSecurityHanders 객체를 추가한다.

app.js

var config = {
  appRoot: __dirname, // required config

  swaggerSecurityHandlers: {
    api_key: function (req, authOrSecDef, scopesOrApiKey, cb) {
      // your security code
      if ('my_key' === scopesOrApiKey) {
        cb();
      } else {
        cb(new Error('access denied!'));
      }
    }
  }
};

여기서는 간단히 api_key를 ‘my_key’ 문자열로 설정했다. swagger-edit 툴을 이용해 스웨거 문서에 api_key를 정의하고 설정할 수 있다. 만약 각 API별로 설정할 경우에는 해당 프로토콜에 security를 추가하면 된다.

swagger.yaml

securityDefinitions:
  api_key:
    type: apiKey
    in: query
    name: api_key
security:
  - api_key: [  ]    

이렇게 설정하고 swagger ui 상단에 api key를 입력하지 않으면 access denied! 메세지가 담긴 Response Body를 응답 받는다.

Dynamic host

동적 호스트명을 설정해야하는 경우 서버 아이피 주소를 app.js 에서 swaggerEpress 객체 설정을 통해 변경할 수 있다.

app.js

SwaggerExpress.create(config, function(err, swaggerExpress) {
  if (err) { throw err; }

  // Dynamic swagger host
  swaggerExpress.runner.swagger.host = 'server ip'
  *** 이하 생략 ***

Reference

• npm, (July 7, 2020), https://www.npmjs.com/package/swagger-ui-express

• doopark, (July 7, 2020), https://dooopark.tistory.com/8

• jeonghwan-kim, (July 7, 2020), http://jeonghwan-kim.github.io/swagger-node/

• hyeong412.log, (July 7, 2020), https://velog.io/@hyeong412/TIL-Express-에-Swagger-사용하기-xkk43n5icz