Swagger
RESTful API 문서 만들기 feat. YAML
code.ryan.lee@gmail.com
Introduction
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.
Introduction
Why API Docs?
Test pyramid
Why API Docs?
'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*$/);
Why API Docs?
2. Black-box Test with supertest
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)
GET /users/{user_id}
Why API Docs?
3. UI Test
RESTAPI Doesn’t have UI
-
API test tool like Postman
-
HTML/JS 로 프로토타입 만들고 테스트
-
API 제공자가 Test-bed를 제공
RESTful APIs
Just Docs
RESTful APIs
RESTful APIs
Github
RESTful APIs
With Test-bed
Swagger
Main purpose
-
API 문서화
-
문서 유지 보수
-
문서 자동 갱신
-
Java Spring Framework
-
Swagger
My purpose
-
API 문서화
-
Test-bed
-
For user's convenience
-
For tester's convenience
-
For {X}'s convenience
Swagger
gAPI with Swagger
Swagger
With Express.js
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
YAML
YAML Ain’t Markup Language
XML, C, 파이썬, 펄, RFC2822에서 정의된 e-mail 양식에서 개념을 얻어 만들어진 사람이 쉽게 읽을 수 있는 데이터 직렬화 양식이다.
YAML
How to use
---
- Lil Dicky
- Rae sremmurd
- R.City
---
[Lil Dicky, Rae sremmurd, R.City]
배열 List
-
YAML
How to use
---
name: Lil Dicky
birth: 1988
born: United States
---
{name: Lil Dicky, birth: 1988, born: United States}
객체 hash
:
YAML
---
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']
How to use
indent : space 사용
YAML
name: hak
age: 27
programmer: true
money:
blog: http://sanghaklee.tistory.com/
lang:
- JavaScript
- PHP
- Java
JSON vs YAML
{
"name": "hak",
"age": 27,
"programmer": true,
"money": null,
"blog": "http://sanghaklee.tistory.com/",
"lang": ["JavaScript", "PHP", "Java"]
}
Conclusion
멋진, 으스대다
swagger
By SangHak Lee
swagger
- 53,552