우분투(Ubuntu) 서버에서 스웨거(Swagger) 설치 및 사용 방법

※ 스웨거(Swagger) 설치하기 ※

  우분투(Ubuntu)와 같은 리눅스 서버에 스웨거(Swagger)를 설치하기 위해서 선택할 수 있는 가장 간단한 방법은 npm을 이용해 swagger를 설치하는 것입니다. 바로 다음과 같은 명령어를 통해 설치를 진행해보겠습니다.

sudo apt install npm
sudo npm install -g swagger

  스웨거(Swagger)가 설치된 이후에는 [swagger project create] 명령어를 이용해 스웨거 프로젝트를 생성할 수 있습니다.

swagger project create {프로젝트 이름}

  프로젝트를 생성할 때는 어떤 프레임워크를 이용해서 스웨거 프로젝트를 생성할 지 결정할 수 있습니다. 저는 자바스크립트 기반의 서버 프레임워크인 익스프레스(Express)를 선택하겠습니다. 또한 저는 프로젝트 이름을 swagger라고 설정하겠습니다.

  이후에 생성된 프로젝트 폴더로 이동하여 [swagger project start] 명령어를 이용해 스웨거를 동작시킬 수 있습니다.

# [Express] 프로젝트 설정하기
cd swagger
swagger project start

  스웨거 프로젝트는 기본적으로 10010번 포트로 실행됩니다.

  혹시 AWS EC2 서버를 이용하는 분들은 다음과 같이 [보안 그룹]의 [인바운드 규칙 편집]에서 10010번 포트를 열어주셔야 합니다.

  결과적으로 다음과 같이 우리의 서버에 10010번 포트를 이용해 접속할 수 있습니다. 스웨거 프로젝트가 처음 생성되면 기본적인 경로로 /hello?name={이름}의 형태로 API를 사용해 테스트 할 수 있습니다.

※ 스웨거(Swagger) 항상 실행시키기 ※

  이제 서버에서 스웨거가 항상 실행되고 있는 상태로 만들 필요가 있습니다. 이를 위해 다음과 같이 bg 및 disown -h 명령을 이용합니다.

# [Ctrl] + Z 입력하여 현재의 Swagger 서버 실행 종료하기
bg
disown -h

  이후에 다음과 같이 netstat 명령을 이용하여 스웨거가 항상 실행되고 있는 것을 확인할 수 있습니다.

※ 스웨거(Swagger) UI 기능 넣기 ※

  스웨거(Swagger) UI 기능을 넣기 위해서는 app.js 파일을 수정하여 swagger-ui 미들웨어 라이브러리를 불러오시면 됩니다. 이 때 소스코드 상에서 API를 호출할 대상이 되는 서버의 아이피와 포트 번호를 입력하여 실행시키면 됩니다. 뿐만 아니라 공인 IP가 있는 서버를 이용하는 경우, 해당 IP를 넣으셔야 합니다.

'use strict';

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

var SwaggerExpress = require('swagger-express-mw');

var app = require('express')();

module.exports = app; // for testing

var config = {

  appRoot: __dirname // required config

};

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

  if (err) { throw err; }

  swaggerExpress.runner.swagger.host = '아이피:10010';

  app.use(SwaggerUi(swaggerExpress.runner.swagger));

  // install middleware

  swaggerExpress.register(app);

  var port = process.env.PORT || 10010;

  app.listen(port);

  if (swaggerExpress.runner.swagger.paths['/hello']) {

    console.log('try this:\ncurl http://127.0.0.1:' + port + '/hello?name=Scott');

  }

});

  이후에 /docs 경로로 접속을 하면 다음과 같이 Swagger UI가 등장합니다. 다만 이렇게 누구든지 접속할 수 있는 경로에 UI가 존재하면, 누구든지 해당 경로에 접속해서 테스트해 볼 수 있다는 문제점이 존재합니다. 따라서 API 키를 설정하여 쉽게 접속할 수 없도록 해야 합니다.

  그러므로 API Key를 이용했을 때만 Swagger를 사용할 수 있도록 보안 처리를 해줍시다. sudo vi app.js를 입력하여 app.js를 열어서 다음과 같이 config 변수의 내용을 수정해주도록 하겠습니다.

var config = {

  appRoot: __dirname, // required config

  swaggerSecurityHandlers: {

    api_key: function (req, authOrSecDef, scopesOrApiKey, cb) {

      // API 키 값이 'my_key'일 경우에만 허용합니다.

      if ('my_key' === scopesOrApiKey) {

        cb();

      } else {

        cb(new Error('access denied!'));

      }

    }

  }

};

  이어서 sudo vi api/swagger/swagger.yaml를 입력하여 swagger.yaml 파일을 열어서 스웨거 파일을 작성할 수 있습니다. 앞서 명시한 API Key를 적용해보도록 하겠습니다. 다음의 내용을 기존에 만들어진 swagger.yaml 문서에서 'definitions' 부분의 바로 위에 넣습니다.

securityDefinitions:

  api_key:

    type: apiKey

    in: query

    name: api_key

security:

  - api_key: [  ]   

  이제 다시 프로젝트를 실행해서 테스트 해보면 다음과 같습니다. API를 호출하기에 앞서 자신이 설정한 키를 상단에 넣어주세요.

  만약에 키를 넣지 않고 호출하면 다음과 같이 오류 메시지가 출력됩니다.

  반면에 키를 넣고 호출하면 api_key라는 파라미터로 키 값이 함께 전송되며 다음과 같이 정상적으로 결과가 출력됩니다.