don't stop believing

Ubuntu에 Swagger 설치 본문

Tools/Swagger

Ubuntu에 Swagger 설치

Tongchun 2017. 12. 20. 17:23

API Document 관리를 위해 Swagger를 사용해 봅시다.

Swagger는 node.js의 모듈로 설치됩니다.

[https://swagger.io/]


먼저 Ubuntu에 node.js를 설치하기 전에 apt-get을 업데이트 해줍니다.

$ sudo apt-get update && sudo apt-get -y upgrade

이제 node.js를 설치합니다.

$ curl -sL https://deb.nodesource.com/setup_9.x | sudo -E bash -
$ sudo apt-get install -y nodejs

최신 버전을 확인하려면 아래 url에서 확인할 수 있습니다.

[https://github.com/nodesource/distributions]

npm이 잘 설치되었는지 버전을 확인해 봅시다.

$ npm -v
5.5.1

이제 npm으로 swagger를 설치합니다.

$ sudo npm install -g swagger

설치가 완료되었다면 이제 swagger 명령으로 관리할 수 있습니다.

  • swagger project create : 노드 프로젝트 생성
  • swagger project edit : swagger-edit으로 swagger 문서 편집
  • swagger project verify : swagger 문서 문법 체크
  • swagger project start : 노트 프로젝트 시작
  • swagger project test : 유닛 테스트

swagger 프로젝트를 생성해 봅시다. 저는 macaron-swagger라고 이름을 하겠습니다.

$ swagger project create macaron-swagger
? Framework? 
  connect 
❯ express 
  hapi 
  restify 
  sails 

swagger project create <프로젝트명>으로 swagger를 생성하면 node.js의 Framework을 선택하게 됩니다.

각 framework에 대한 비교는 아래 url에서 간략히 볼 수 있습니다.

https://npmcompare.com/compare/connect,express,hapi,swagger-express,swagger-express-middleware

저는 express를 선택했습니다.


swagger project가 생성되었다면 macaron-swagger폴더가 생성된 것을 확인할 수 있습니다.

폴더로 들어가서 swagger가 정상적으로 설치 되었는지 실행해 봅시다.

$ cd macaron-swagger
$ swagger project start
Starting: /home/ngle/macaron-swagger/app.js...
  project started here: http://localhost:10010/
  project will restart on changes.
  to restart at any time, enter `rs`
try this:
curl http://127.0.0.1:10010/hello?name=Scott

브라우저를 열고 curl의 내용을 호출해 봅시다.

swagger가 설치된 서버 IP로 접속합니다.

정상 실행된것을 확인했습니다.


이제 사용할 swagger에 기본 설정을 해야 합니다.

Ubuntu를 로컬에서 실행하고 있다면 swagger project edit 명령으로 editor를 실행할 수 있습니다.

만약 ssh로 Ubuntu에 접속하고 있다면 /api/swagger/swagger.yaml 파일에서 수정을 하면 됩니다. swagger project edit로 열었을때 보이는 파일이 swagger.yaml파일입니다.


실행한 swagger project에 swagger-ui를 연동해 줘야 합니다.

app.js 파일을 vim으로 열고 SwaggerUi 변수를 추가하고 require('swagger-tools/middleware/swagger-ui');를 할당합니다. 그리고 SwaggerExpress.create{} 안에 SwaggerUi를 추가합니다.

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);

});

swagger project start로 시작 후 브라우저에서 /docs 경로에 접속하면 swagger ui가 보입니다.

api_key도 설정해 줍니다.

swagger를 통해 api를 호출할 때 api_key를 적용하면 api_key가 파라메터로 추가되어 요청됩니다.API 접근에 대한 보안 설정입니다.

app.js 파일을 열고 SwaggerExpress의 config 객체에 swaggerSecurityHanders 객체를 추가합니다.

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

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

};

저는 macaron이라고 api_key를 적용했습니다. 그리고 swagger-edit 또는 /api/swagger/swagger.yaml 에서 아래와 같이 securityDefinitions를 추가해 줍니다.

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

swagger project start 후 swagger ui의 api_key에 적용한 key(macaron)을 넣지 않고 api를 호출할 경우 아래와 같이 access denied! 에러가 발생합니다.


Dynamic host도 적용해 봅시다.

서버에 올라갈 경우 서버 IP를 적용해야 합니다. app.js파일에서 swaggerExpress 객체를 생성해 주면 됩니다. swaggerExpress는 swagger-ui보다 먼저 생성되어야 합니다.

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

  // Dynamic swagger host
  swaggerExpress.runner.swagger.host = '192.168.1.12:10010';
  
  // add swagger-ui (/docs)
  app.use(SwaggerUi(swaggerExpress.runner.swagger));

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

저는 테스트 서버의 IP와 Port를 적용했습니다.


'Tools > Swagger' 카테고리의 다른 글

Visual Studio Code에서 swagger 보기  (0) 2018.06.18
Swagger의 yaml 파일 경로 변경  (0) 2018.01.19
swagger editor 설치 (on Mac)  (0) 2017.12.21
Comments