이상학의 개발블로그

[Swagger] RESTful API 문서 만들기 feat. YAML 본문

Dev Tools

[Swagger] RESTful API 문서 만들기 feat. YAML

학학이 2017. 4. 12. 19:07

Introduction

Node.js를 사용해서 API 서버를 개발해야 하는 상황이 생겼다.
기존에 있는 API 서버를 Node.js 언어로 바꾸는 것이 아니고 새로운 API 서버를 만들어야 하는 상황이었다.
개발된 API 설명서를 사용자에게 제공하면서 API를 테스트할 수 있는 Test-bed를 제공하면 좋을 것이라 생각했다.
기존의 Open API들을 사용할 때, Postman을 이용해서 문서의 내용을 복-붙 후 테스트해보고 다시 개발하는 과정이 귀찮다고 느낀 것이다.
Open API 문서 자체에서 테스트를 할 수 있으면 사용자의 편의성이 높아질 것이라는 생각에 찾게 된 것이 Swagger다.

Swagger

THE WORLD’ S MOST POPULAR API FRAMEWORK

Swagger is a powerful open source framework backed by a large ecosystem of tools that helps you design, build, document, and consume your RESTful APIs.

Swagger를 사용하면 쉽게 RESTful API 서비스를 설계, 제작, 문서화할 수 있다.


Why API Docs?

다른 서비스의 Open API를 사용하기 전에 처음으로 해야 할 일이 뭘까?
사용하려는 서비스의 홈페이지에 들어가서 API 사용 설명서를 읽는 것이 먼저일 것이다.
API 사용자는 API 문서에 의존할 수밖에 없다.

Test pyramid

필자가 집중한 것은 Test-bed 의 역할을 겸한 API 문서를 작성하는 것이다.

Application을 개발할 때, 테스트는 중요하다.
많은 개발자들이 시간과 노력이 많이 들어도 TDD를 지향하는 데는 이유가 있다.
확실한 Test case를 통한 Unit test는 유지보수 시 큰 효과를 발휘한다.


Unit test는 빠르다. 테스트를 하는데 걸리는 시간은 오래 걸리지 않는다.
Unit test는 테스트할 case가 많고 case 작성에 시간이 많이 들지 테스트가 수행되는 시간은 금방이다.(컴퓨터가 하니깐!)
그러나, UI test는 테스트 과정이 느리고 비용이 많이 든다. 보통 UI test는 사람의 수작업을 필요로 하는 경우가 많기 때문이다.


Test case

1. Unit Test with mocha, should.js

'ab'.should.be.equalOneOf('a', 10, 'ab');
res.should.be.json();
promise.should.be.Promise();
['user_1', 'user_1000'].should.matchAny(/^(user_)+[1-9]{1}\d*$/);

Unit test는 함수, 메소드의 결과 값이 예상한 결과 값과 일치하는지 즉, 개발자의 의도대로 작동하는지 검사한다.

2. Black-box Test with supertest

GET /users/{user_id}

request(app)
.get('/users/user_10')
.set('Accept', 'application/json')
.expect(200)
.then(response => {
response.should.be.json();
assert(response.body.name, 'hak')
})
request(app)
.get('/users/123')
.set('Accept', 'application/json')
.expect(400)

Black-box는 내부 로직에 대한 이해 없이 올바른 입력과 올바르지 않은 입력을 사용해서 올바른 출력을 판별한다.

3. UI Test

완벽한 Test-case를 만들 순 없지만 위의 tool들을 이용하면 UI 테스트도 어느 정도 자동화할 수 있다.


REST API Doesn’t have UI

그러나, REST API는 화면이 없다.
API 사용자가 Open API를 사용하기 전에 테스트할 수 있는 방법이 뭐가 있을까?

  1. API test tool like Postman
  2. HTML/JS로 프로토타입 만들고 테스트
  3. API 제공자가 Test-bed를 제공

NOTE : Postman은 정말 잘 만든 API test-tool이다. 사용한 경험이 없다면, 꼭 한 번 사용해보길 권한다.
RESTful 한 API를 테스트할 수 있을 뿐만 아니라, API를 언어별 코드로 만들어주고 Test-runner를 만들어서 전체 API를 테스트하고 실행 결과를 분석할 수 있다.


RESTful APIs

Just Docs

아래 3가지 Open API들은 문서가 정적으로 제공된다는 공통점을 갖고 있다.
즉, 문서 자체에서 Test를 해볼 수 없다.

  • Facebook
    • GET graph.facebook.com/v2.5/me HTTP/1.1
  • Github
    • GET api.github.com/users/sanghaklee HTTP/1.1
  • Kakao
    • POST kauth.kakao.com/oauth/token HTTP/1.1

With Test-bed

문서만 제공하는 API 달리 몇몇 API 문서들은 Test-bed를 함께 제공한다.
주관적이지만, Iamport의 API 문서가 개발자 친화적이라 생각한다.


Swagger

Swagger의 주된 목적은 RESTful API를 문서화시키고 관리하는 것이다.
API 문서를 일반 Document로 작성하면 API 변경 시마다 문서를 수정해야 하는 불편함이 있는데, Swagger 같은 Framework를 이용하면 이를 자동화할 수 있다. (Spring boot 사용 시)

Swagger의 주된 목적은 API 문서의 효율적 작성이지만, 필자가 중점을 둔 것은 테스트 환경의 제공이다.
Swaager로 API 문서를 만들면 문서 자체가 API에 대한 설명이면서 Test-bed이다.
사용자는 API 문서를 읽으면서 바로 해당 API에 대해 테스트를 해볼 수 있다.

Unit -> Black-box 테스트 과정을 통과 후 배포해도 실제 Service-level에서 오류가 발생할 수 있다.
이러한 이유가 우리가 Open API를 사용 전 Postman으로 테스트를 해보는 이유이다.
Swagger를 이용하면 이러한 API Test 환경을 문서와 함께 제공하기 때문에 Postman 같은 tool을 이용할 필요가 적어진다.

이것이 Swagger를 포함한 API Framework를 사용하는 이유이다.

UI

아래의 링크로 이동하면 Swagger 예제 API Docs를 볼 수 있다.

Editor

Swagger Editor를 이용하면 쉽게 Swagger 문서 모델을 만들 수 있다.
http://editor.swagger.io/#!/

---
swagger: '2.0'
info:
version: 1.0.0
title: Echo
description: |
#### Echos back every URL, method, parameter and header
Feel free to make a path or an operation and use **Try Operation** to test it. The echo server will
render back everything.
schemes:
- http
host: mazimi-prod.apigee.net
basePath: /echo
paths:
/:
get:
responses:
200:
description: Echo GET
post:
responses:
200:
description: Echo POST
parameters:
- name: name
in: formData
description: name
type: string
- name: year
in: formData
description: year
type: string


Other

Swagger와 비슷하게 API Docs를 만들어주는 서비스가 있다.


YAML

Swagger는 기본적으로 YAML 포맷을 이용해 Docs 문서를 작성한다.
물론 JSON 포맷으로도 가능하지만, Swagger가 기본으로 채택한 YAML도 살펴볼 필요가 있다.

  • XML, C, 파이썬, 펄, RFC2822에서 정의된 e-mail 양식에서 개념을 얻어 만들어진 사람이 쉽게 읽을 수 있는 데이터 직렬화 양식이다.
  • YAML Ain’t Markup Language
    • YAML은 마크업이 아닌 데이터 자체를 중요시 여긴다는 뜻에서 지어진 이름이다.

문법

주석 : #

# 이 라인은 주석입니다. 

배열(list) : -

- Lil Dicky
- Rae sremmurd
- R.City
[Lil Dicky, Rae sremmurd, R.City]

- 을 사용하지 않고 JSON의 [] 을 사용해서 한 줄로 배열을 나타낼 수 있다.


객체(hash) : :

name: Lil Dicky
birth: 1988
born: United States
{name:Lil Dicky, birth: 1988, born: United States}

JSON의 {} 을 사용해서 한 줄로 객체를 나타낼 수 있다.


분류 - 공백(space)을 이용해 각 데이터를 구분

---
intro: Yeah bitch, check my profile. Perfect, but you are not.
profile:
  name: beenzino
  birth: 1987
  sns:
    youtube: https://www.youtube.com/channel/UCyFkumV0dfLxSY602sIYNvw
    insta: https://www.instagram.com/realisshoman/
  song:
    single: [Nike Shoes, Aqua Man, Up All Night]
    crew: [연결고리, '11:11']

tab 은 사용하지 못한다. 시스템마다 tab을 표현하는 방법이 다르기 때문에 공백만 사용.

More


JSON vs YAML

JSON

{
"name": "hak",
"age": 27,
"programmer": true,
"money": null,
"blog": "http://sanghaklee.tistory.com/",
"lang": ["JavaScript", "PHP", "Java"]
}

YAML

name: hak
age: 27
programmer: true
money: 
blog: http://sanghaklee.tistory.com/
lang:
- JavaScript
- PHP
- Java

JSON -> YAML
YAML -> JSON

Conclusion

There is no silver bullet.
모든 문제에 만능 해결 key는 없다. SW 공학에서 여러 가지 방법론을 평가할 때 사용하는 말이다.
경우에 따라 RESTful API에서 API Docs가 필요하지 않을 수 있다.
그러나, 높은 완성도와 사용자 편의성을 위해 Docs를 만드는 것이 좋다.
위에서 본 Facebook, Github와 같이 오직 문서로만 Docs를 만들 수 있고, 좀 더 나아가 간단한 테스트 환경을 만들어 줄 수 있다.
만약, API Docs를 만들면서 Test 환경을 같이 제공해 주고 싶다면 Swagger가 좋은 선택이 될 수 있다.

Swagger의 사전적 의미처럼 멋지고 으스댈 수 있는 API 문서를 만들어 보자!


NOTE 
Swagger를 이용해서 Java Spring-boot와 유사하게 Code-level에서 API docs를 만들어주는 패키지를 찾았다. 
swagger-jsdocswagger-ui-express 그리고 이 둘을 합쳐서 Express 기반 swagger-express-jsdoc을 만들었다. 
API를 파악해서 자동으로 docs를 만들어 주진 않지만, code에 YAML 형식을 jsdoc 형식으로 주석 처리하면 자동으로 문서를 만들어준다.

References


Comments