안경잡이개발자

728x90
반응형

※ 스웨거(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라는 파라미터로 키 값이 함께 전송되며 다음과 같이 정상적으로 결과가 출력됩니다.




728x90
반응형

'Swagger' 카테고리의 다른 글

Swagger Hub를 이용한 REST API 관리  (2) 2019.01.20

728x90
반응형

  스웨거(Swagger)는 대표적인 API 관리 도구입니다. 일반적으로 프로그램을 개발할 때에는 백 엔드 개발자와 프론트 엔드 개발자가 서로 협력하는 형태로 개발을 진행하게 됩니다. 이 때 백 엔드 프로그램과 프론트 엔드 프로그램 사이에서 정확히 어떠한 방식으로 데이터를 구조 받을 지에 대한 명세가 필요할 수 있습니다. 이러한 내용이 담긴 문서를 일반적으로 API 명세서라고 말합니다.


  스웨거 허브는 다양한 프로젝트의 API 관리 기능을 지원해주는 스웨거 서비스입니다. 여러 명의 개발자가 스웨거 허브에 가입하여 하나의 프로젝트에 대한 API를 작성하고, 테스트 해 볼 수 있습니다.


  ▶ 스웨거 허브(Swagger Hub): https://swagger.io/tools/swaggerhub/


  바로 한 번 스웨거 허브에 가입한 뒤에 로그인을 하여 실습을 진행해보도록 하겠습니다. 또한 기본적인 Open API 작성 방법에 대해서도 소개하겠습니다. 일단 바로 사이트에 접속하여 [Sign In]에 들어가 회원가입을 진행하겠습니다.



  스웨거 허브(Swagger Hub)를 이용하시면 됩니다.



  회원가입은 깃 허브(Git Hub)를 이용해서 진행할 수도 있지만, 저는 이메일을 이용해서 회원가입을 진행하겠습니다. 기본적으로 스웨거 허브는 혼자서 개인적인 목적으로 사용할 때는 무료로 이용할 수 있습니다. 다만 팀 규모로 이용할 때는 가격 정책이 적용될 수 있답니다.



 회원가입 이후에 조직(Organization)을 생성하여, 자신의 팀원들을 초대할 수도 있습니다. 저는 단순히 예제만 다루는 목적으로 이용할 것이므로 대충 작성하고 넘어가도록 하겠습니다.



  결과적으로 로그인을 진행하게 되면 새로운 API(New API)를 만들 수 있습니다. 말 그대로 특정한 프로젝트 하나에 대한 API 명세서를 작성할 수 있습니다.



  이후에 API를 생성할 때는 설정을 진행할 수 있습니다. Open API 버전은 현재 2.0이 가장 많이 사용되며, 템플릿(Template)을 정해줄 수 있습니다. 템플릿은 API 명세서를 더 쉽게 작성할 수 있도록 도와주는 것으로, 기본적인 API 명세서 형태를 미리 갖춘 문서를 의미합니다.


  가장 기본적인 예제인 펫 스토어(Pet Store) 예제를 통해 API 템플릿을 구성해보도록 하겠습니다. 말 그대로 애견샵 컨셉의 프로젝트 API 명세서라고 이해하시면 됩니다. 이를 많이 참고하셔서 향후 프로젝트의 API를 구성하시면 효율적이에요.



  프로젝트가 생성되면 바로 다음과 같은 화면을 만날 수 있습니다. 처음 이러한 화면을 만나면 당황스러울 수 있으나 익숙해 지면 정말 효율적인 화면 구성이라는 것을 이해할 수 있어요.


  ▶ 화면의 왼쪽에는 API 내비게이션(Navigation)이 존재합니다.

  ▶ 그리고 중간에는 API 명세서의 에디터(Editor)가 들어가 있습니다. 실질적으로 이 소스코드가 API 명세서의 핵심이라고 할 수 있습니다.

  ▶ 오른쪽에는 실제로 API 명세서의 사용자 입장에서 테스트를 할 수 있는 UI 다큐먼트(UI Docs)가 존재합니다.



  실제로 에디터에 작성되어 있는 소스코드가 UI 다큐먼트에서 어떻게 출력되는지 확인해보도록 하겠습니다. 기본적으로 스웨거 코드를 작성할 때는 특정한 API의 경로에 대해서 명시한 뒤에, HTTP 메소드(Method)에 대해서 명시합니다. 이후에 그 동작 과정에 대해서 적어주면 됩니다.


  ▶ GET 방식: 데이터 조회

  ▶ POST 방식: 새로운 데이터의 삽입 및 수정

  ▶ PUT 방식: 기존 데이터의 수정

  ▶ DELETE 방식: 기존 데이터의 삭제


  아래 예제는 /pet/{petId}라는 경로에 GET 방식 및 POST 방식으로 접근했을 때의 처리 방식에 대해서 보여주고 있습니다.



  실제로 오른쪽의 UI 다큐먼트를 보시면, 다음과 같이 테스트 환경이 구축되어 있는 것을 확인할 수 있습니다. 파라미터(Parameter)를 설정하여 데이터를 전송할 수 있습니다. 데이터를 전송하면 서버는 그에 대한 응답(Response)를 주게 됩니다.


  기본적으로 응답 코드가 200인 경우 정상적으로 데이터를 처리하여 반환했다는 것을 의미합니다.



  실제로 다음과 같이 응답 코드 200과 함께 JSON 형태의 응답(Response) 데이터가 출력된 것을 확인할 수 있습니다. 이처럼 REST API 형태로 데이터를 주고 받을 때는 JSON 형식을 이용한다는 특징이 있습니다.



  또한 스웨거 API에서는 인증(Authorize)에 대한 처리 정보도 관리할 수 있습니다.



  그리고 각 데이터 모델(Model)에 대해서도 정의할 수 있는데요, 일반적으로 데이터베이스에 기록되어 있는 모델 형태를 그대로 가져와 사용합니다. 아래 소스코드에서는 주문(Order) 오브젝트에 대해 정의하고 있습니다.



  이어서 다음과 같이 전체 API에 대한 개요를 작성할 수 있으며, 추가적으로 태그(Tag)를 넣어서 각 API를 분류시킬 수 있습니다. 이러한 구성 덕분에 스웨거(Swagger) API는 단 하나의 소스코드로 하나의 단일 프로젝트에 대한 전체 API를 명세할 수 있는 것입니다.



  또한 작성된 코드를 다운로드(Download)하여 여러 개의 프로그래밍 언어 환경에 붙여넣기 할 수 있습니다. [Export] - [Download API]에 들어가서 원하는 형태로 API를 다운로드 해주세요.



  대표적인 형태인 [JSON Resolved]로 다운로드를 진행하면 다음과 같은 압축 파일이 다운로드 됩니다.



728x90
반응형