안경잡이개발자

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
반응형

  AWS EC2를 이용하다 보면 볼륨(Volume)이 초과되어 새로운 라이브러리 등을 설치하는 데에 제약이 생길 수 있습니다. 이번 시간에는 정해진 서버 용량인 볼륨(Volume)이 부족할 때 볼륨의 용량을 늘리는 방법에 대해서 소개하고자 합니다.


  따라서 가장 먼저 AWS EC2 관리 페이지로 이동하여 [볼륨] 탭으로 이동하시면 됩니다.



  이후에 자신이 늘리고자 하는 인스턴스의 [볼륨]을 찾으셔서 [작업] - [볼륨 수정]에 들어가시면 됩니다. 저는 크기가 8GB인 볼륨을 16GB로 늘려보도록 하겠습니다.




  이후에 볼륨을 원하는 크기로 증가시키시면 됩니다. 정말 간단합니다.



  수정 내역이 반영되기까지는 일반적으로 10분 ~ 1시간 내외의 시간이 소요될 수 있습니다.




  결과적으로 다음과 같이 처리가 진행 인 것을 확인할 수 있습니다.



  저는 약 10분의 시간이 흐른 뒤에 다음과 같이 초록색으로 볼륨 증가 완료 처리 되었습니다.



  이제 인스턴스를 재부팅 해주시면 안정적으로 적용됩니다.



  다시 서버에 접속하여 다음의 명령어로 볼륨 내의 용량이 어떻게 배정되어 있는지 확인할 수 있습니다. 저는 성공적으로 기존의 8GB의 디스크 용량이 16GB로 증가한 것을 확인했습니다.


  df -Th


728x90
반응형

728x90
반응형

  JSON, YAML, XML은 모두 데이터(Data)를 표현하는 형식입니다. 다만 그 형태와 문법은 조금씩 다르다는 점에서 그 차이점을 바르게 인지하고 있는 것이 중요합니다. 따라서 이번 시간에는 XML, JSON, YAML에 대해서 공부한 뒤에 이를 비교하는 시간을 가져보도록 하겠습니다. 세 가지 중에서 무엇이 가장 효과적이라고 말할 수는 없으며 상황에 맞는 형식을 이용할 수 있으면 됩니다.


1. XML


  XML데이터를 표현하기 위하여 많이 사용되어 온 방식으로 HTML과 흡사한 구조를 가지고 있습니다. XML이 가지는 고유한 문법이 있다는 점에서 소프트웨어 및 하드웨어에 대하여 독립적으로 데이터를 처리할 수 있습니다. XML의 특징은 꺽쇠(<>)입니다. XML은 트리(Tree) 계층 구조를 가지고 있습니다. 루트(Root) 요소부터 시작해 여러 개의 자식을 계층적으로 포함하게 됩니다.


<?xml version="1.0" encoding="UTF-8"?>

<users>

  <user>

    <name>홍길동</name>

    <score>95</score>

    <hobby>

      <element>Soccer</element>

      <element>Ninza</element>

    </hobby>

  </user>

  <user>

    <name>이순신</name>

    <score>100</score>

    <hobby>

      <element>Sing</element>

      <element>Dancing</element>

    </hobby>

  </user>

  <user>

    <name>나동빈</name>

    <score>97</score>

    <hobby>

      <element>Coding</element>

      <element>Hiding</element>

    </hobby>

  </user>

</users>


  또한 XML은 유효성 검증(Validation)을 통해서 올바르게 작성되었는지 확인할 수 있습니다.


  ▶ XML 유효성 검증 사이트: https://www.xmlvalidation.com/



※ XML 선언 ※


  XML 문서는 기본적으로 <xml> 태그를 이용해서 XML 문서임을 명시할 수 있습니다. 속성으로는 다음과 같은 것들을 넣을 수 있습니다.


 - version: XML 문서의 버전을 명시합니다.

 - encoding: XML 문서의 문자 셋(Character Set)을 명시합니다. 일반적으로 UTF-8을 사용합니다.

 - standalone: XML 문서 외부 소스 데이터에 의존하는지의 여부를 명시합니다.


  따라서 일반적으로 다음과 같이 작성할 수 있습니다.


<?xml version="1.0" encoding="UTF-8"?>


※ XML 문법 ※


  XML 문서는 규칙적인 형태를 가지고 있습니다. 가장 중요한 문법으로는 XML 요소들은 시작 태그와 종료 태그로 구성된다는 점입니다. 태그는 꺽쇠(<>)를 이용해 명시하며, 닫는 태그에는 슬래시(/)를 함께 넣어줍니다. 예를 들어 TITLE이라는 이름의 태그를 사용한다고 하면 다음과 같이 사용할 수 있습니다.


  <TITLE>내용</TITLE>


  이 때 시작태그와 종료 태그는 대소문자까지 모두 동일해야 합니다. 또한 태그 안에 속성을 명시할 때는 따옴표를 넣어주어야 합니다. 속성을 사용할 때는 다음과 같이 사용할 수 있습니다.


  <TITLE color="red" type="bold">내용</TITLE>


※ XML 주석 ※


  XML은 주석(Comment)을 넣을 수 있습니다. XML의 주석은 <!-- 주석 내용 --> 형태로 사용할 수 있습니다.


2. JSON(JavaScript Object Notation)


  JSON 또한 XML과 비슷하게 데이터를 처리하기 위한 형식입니다. 일반적으로 서버와의 통신 규약인 REST API를 사용할 때 가장 많이 사용되어, 최근에는 XML보다는 JSON 형식이 채택되고 있습니다. 사실상 모든 프로그래밍 언어에서 JSON을 지원한다는 점에서 XML과 YAML에 비해서 채택률이 높아지고 있습니다. JSON은 주석을 사용할 수 없다는 특징이 있습니다.


  가장 먼저 XML 형식을 JSON 형식으로 바꾸는 예제를 확인하며 문법을 확인해보도록 하겠습니다.


[ 변환 이전 ]


<?xml version="1.0" encoding="UTF-8"?>

<users>

  <user>

    <name>홍길동</name>

    <score>95</score>

    <hobby>

      <element>Soccer</element>

      <element>Ninza</element>

    </hobby>

  </user>

  <user>

    <name>이순신</name>

    <score>100</score>

    <hobby>

      <element>Sing</element>

      <element>Dancing</element>

    </hobby>

  </user>

  <user>

    <name>나동빈</name>

    <score>97</score>

    <hobby>

      <element>Coding</element>

      <element>Hiding</element>

    </hobby>

  </user>

</users>


[ 변환 이후 ]


{

"users": {

"1": {

"name": "홍길동",

"score": 95,

"hobby": ["Soccer", "Ninza"]

},

"2": {

"name": "이순신",

"score": 100,

"hobby": ["Sing", "Dancing"]

},

"3": {

"name": "나동빈",

"score": 97,

"hobby": ["Coding", "Hiding"]

}

}

}


  기본적으로 JSON 형식에서는 키(Key) 값이 서로 다른 형태로 사용됩니다. 그래서 위와 같이 사용자를 1, 2, 3으로 구분하는 방식으로, 사용자 명단에 대한 내용을 작성할 수 있습니다. 다만 JSON은 XML과 다르게 꺽쇠가 사용되지 않고 대괄호({})와 큰 따옴표를 이용해 계층형 구조를 형성한다는 특징이 있습니다.


  ▶ JSON 유효성 검증 사이트: https://www.xmlvalidation.com/


  JSON 또한 유효성 검증 사이트에서 그 문법적 유효성을 검증할 수 있습니다.



3. YAML


  YAML 또한 JSON과 비슷하게 사람이 읽기 쉬운 형태의 데이터 표현 형식입니다. YAML은 XML과 문법적으로 유사한 점이 많습니다. YAML에서도 주석을 사용 가능하며 개행, 공백으로 블록을 인식합니다. 다만, 태그를 사용하지 않고 공백 위주로 데이터를 구분하므로 한 줄로 작성할 수 없다는 특징이 있습니다.


  그리고 JSON은 한글 등의 멀티 바이트 문자를 인코딩하여 보여주지만 YAML한글과 같은 유니코드를 그대로 사용할 수 있다는 장점이 있습니다. 일반적으로 API를 만들 때에는 JSON을 사용하며, YAML은 설정 파일을 작성할 때 가장 많이 사용된다는 특징이 있습니다. 심지어 YAML는 상속(Inherit) 등의 기능도 적용할 수 있다는 점에서 효율적입니다.


  앞서 다루었던 사용자 명단 예제를 YAML 형태로 표현하면 다음과 같이 나타낼 수 있습니다.


users:

  1:

    name: 홍길동

    score: 95

    hobby:

      - Soccer

      - Ninza

  2:

    name: 이순신

    score: 100

    hobby:

      - Sing

      - Dancing

  3:

    name: 나동빈

    score: 97

    hobby:

      - Coding

      - Hiding


  ▶ YAML 유효성 검증 사이트http://www.yamllint.com/



  이와 같이 YAML 문서는 위에서 아래로 직렬적으로 작성되어 있다는 점에서 [데이터 직렬화 형식]이라고도 부릅니다. 일반적으로 Swagger API, Spring Boot, Docker 등의 굉장히 많은 환경에서 설정(Conf) 파일 작성을 목적으로 YAML을 사용합니다.

728x90
반응형

728x90
반응형

  일반적으로 자신만의 서버를 구축하고 싶을 때는 가장 손쉬운 형태로 AWS EC2 서비스를 사용할 수 있습니다. AWS EC2에서는 하나의 컴퓨터(Computer) 자원을 하나의 인스턴스(Instance)라고 표현합니다. 이번 시간에는 AWS EC2를 이용하여 우분투(Ubuntu) 리눅스 개발환경을 구축한 뒤에 주피터 노트북(Jupyter Notebook)을 설치하여 외부에서 서버를 쉽게 관리하는 방법에 대해서 알아보도록 하겠습니다.


  다음의 절차를 천천히 따라오시면, AWS에 대해서 아예 모르는 초보자도 30분 안에 AWS 우분투 서버와 Jupyter Notebook을 이용한 개인 서버 환경을 구축하실 수 있습니다. 바로 한 번 AWS EC2 인스턴스부터 만들어 보도록 하겠습니다.


※ AWS EC2 인스턴스 만들기 ※


  AWS 콘솔(Console)에 접속하신 이후에 [EC2] 서비스에 들어갑니다.



  [인스턴스 시작] 버튼을 눌러서 인스턴스를 생성하고 시작할 수 있습니다.



  이후에는 우분투(Ubuntu) 리눅스 서버로 [선택]하여 생성해주겠습니다.



  기본적으로 프리 티어(Free Tier) 서비스를 선택하여 사용하도록 하겠습니다.



  별도의 설정을 바꿀 필요 없이 바로 [시작] 버튼을 눌러서 인스턴스를 구동시킬 수 있어요.



  다만 처음 인스턴스를 시작할 때 [키 페어]를 설정할 수 있습니다. 이 키 페어는 실제로 AWS EC2 서버에 접속하기 위한 목적으로 사용됩니다. 따라서 키 페어를 분실하는 경우 상당히 귀찮은 일이 발생할 수 있습니다. 따라서 개인 드라이브에 소중히 보관하셔야 합니다. 저는 다음과 같이 새로운 키 페어를 생성하도록 하겠습니다.


  결과적으로 키 페어 파일을 다운로드 한 뒤에 [인스턴스 시작]을 눌러주시면 완료됩니다.



※ AWS EC2 인스턴스에 접속하기 ※


  저는 이렇게 만들어진 인스턴스에 [연결] 버튼을 눌러서 접속해보도록 하겠습니다.



  이후에는 다음과 같이 서버에 접속할 수 있는 SSH 명령어가 나옵니다.



  다만 윈도우(Windows) 운영체제에서 우분투 서버에 접속하기 위해서는 키 페어에 대한 귀찮은 [사용 권한 설정]이 필요합니다. 따라서 아까 다운로드 받은 키 페어 파일의 [속성]을 확인하여 [보안] - [고급] 탭으로 이동하시면 됩니다.


  기본적으로 관리자 권한으로만 해당 키 페어를 사용하도록 처리해야 서버에 접속할 수 있어요.



  따라서 원활한 권한 설정을 위해 [상속 사용 안 함] 처리를 진행해주세요.



  그리고 [명시적 사용 권한으로 변환]으로 진행하시면 됩니다.



  이후에 다음과 같이 일반 사용자들(Users)에 대한 모든 권한을 제거해 주시고, 관리자 그룹에서만 접근할 수 있도록 남겨줍니다.



  이제 명령 프롬프트를 관리자 권한으로 실행하여 접속해보도록 하겠습니다.



  해당 키 페어 파일이 존재하는 위치로 이동하여 앞서 확인했던 SSH 명령어로 서버에 접속하시면 됩니다.



  이제 접속이 완료된 것을 확인할 수 있습니다. 최신 우분투에는 기본적으로 깃(Git), 파이썬(Python) 등이 설치가 되어 있습니다. 그러므로 간단히 파이썬을 이용해 정상적으로 구동되는 지의 여부를 확인해보도록 하겠습니다.



※ 주피터 노트북(Jupyter Notebook) 설치하기 ※


  주피터 노트북은 다음과 같이 pip3 명령어를 이용하여 설치할 수 있습니다.


sudo apt-get update
sudo apt-get install python3-pip
sudo pip3 install notebook


※ 주피터 노트북(Jupyter Notebook) 비밀번호 설정하기 ※


  이후에 주피터 노트북(Jupyter Notebook)의 비밀번호를 만들어 보도록 하겠습니다. 파이썬(Python)에서 다음과 같은 명령어로 비밀번호를 입력하여 생성할 수 있습니다.


python3
>> from notebook.auth import passwd
>> passwd()
# 비밀번호 설정한 뒤에 SHA1 값 기록해 놓기



  이제 실제로 주피터 비밀번호 설정 및 접속 설정을 하기 위해서 주피터 환경 설정 파일을 생성하도록 하겠습니다.


jupyter notebook --generate-config
sudo vi /home/ubuntu/.jupyter/jupyter_notebook_config.py



  이제 주피터 환경 설정을 진행하기에 앞서 현재 서버의 내부망 IP 주소를 확인하도록 하겠습니다. 주피터 노트북을 이용해 서버를 개방할 때는 IP 주소 및 포트 번호를 설정해야 하기 때문입니다. 저는 다음과 같이 172.31.20.175라는 IP 주소를 확인할 수 있었습니다.



  이제 다음과 같이 jupyter_notebook_config.py 파일을 열어서 환경 설정 내용을 작성해주시면 됩니다. 기본적으로 내용들이 주석처리 되어 있으므로 소스의 가장 아래 쪽에 다음과 같은 내용을 추가적으로 넣어주시면 됩니다.


c = get_config()
c.NotebookApp.password = u'sha1:{해시 값}'
c.NotebookApp.ip = '{내부 아이피}'
c.NotebookApp.notebook_dir = '{시작 디렉토리}'
# 내부 아이피로는 SSH로 접속했을 때 콘솔 창에 나오는 아이피를 입력하기


  환경 설정을 할 때는 기본적으로 주피터 노트북에 접속하기 위한 비밀번호는 앞서 설정했던 비밀번호의 SHA-1 해시 값을 넣어주시면 됩니다. 이후에 내부 아이피주피터에 접속했을 때 확인하게 되는 시작 디렉토리를 설정하시면 됩니다. 결과적으로 다음과 같이 작성하시면 됩니다.



※ 주피터 노트북(Jupyter Notebook) 실행하기 ※


  이제 주피터 노트북을 실행할 수 있습니다. 저는 루트(Root) 권한을 허용한 형태로 주피터 노트북을 열어보도록 하겠습니다. 말 그대로 주피터 비밀번호만 알고 있으면 해당 서버를 완전히 루트 권한으로 다룰 수 있게 허용한다는 의미입니다.


sudo jupyter-notebook --allow-root

  명령어 입력 이후에는 다음과 같이 8888번 기본 포트로 주피터가 열린 것을 확인할 수 있습니다.



※ 방화벽 설정하기 ※


  이후에 AWS EC2 관리 페이지에서 [보안 그룹] 설정을 통해 8888번 포트 방화벽을 개방할 수 있습니다. 기본적으로 AWS EC2는 보안을 위해 대부분의 포트를 막아놓습니다. 그래서 이와 같이 특정한 서버 프로그램을 운영할 때마다 보안 그룹 설정을 해주어야 합니다.



  이후에 다음과 같이 [인바운드]에서 [편집] 버튼을 눌러 8888번 포트를 [위치 무관]으로 열어주시면 됩니다. 그러면 전세계 어디에서나 우리 서버의 주피터에 접속을 시도할 수 있게 됩니다.



※ 서버에 접속해보기 ※


  이제 준비가 완료되었으므로 주피터(Jupyter)에 접속해보도록 하겠습니다. 우리 AWS EC2 서버의 공인 IP를 확인합니다.



  이제 브라우저에서 해당 아이피에 8888번 포트로 접속하시면 됩니다. 다음과 같이 접속하여 비밀번호를 입력해 보겠습니다.



  접속 이후에는 바로 [New] - [Terminal]에 들어가서 터미널에 접속해보도록 하겠습니다.



  터미널에 접속한 이후에는 루트(Root) 권한을 이용할 수 있는 형태로 서버를 완전히 마음대로 컨트롤할 수 있게 됩니다.



※ 주피터 노트북 항상 켜놓기 ※


  이제 주피터 노트북을 항상 켜놓는 방법에 대해서 소개하겠습니다. 기본적으로 주피터 노트북을 실행하는 명령을 입력한 이후에 동작을 종료하고, bg 명령을 이용해 백 그라운드에서 돌아가도록 처리할 수 있습니다. 이후에 소유권을 포기하면 백 그라운드에서 항상 주피터 서버가 동작하는 상태가 됩니다. 이로써 항상 서버를 열어놓을 수 있습니다. 명령어는 다음과 같습니다.


sudo jupyter-notebook --allow-root
# [Ctrl] + Z 입력하여 실행 종료하기
bg
disown -h




728x90
반응형

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
반응형