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?

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*$/);

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

• selenium

• froglogic

• ranorex

RESTAPI Doesn’t have UI

1. API test tool like Postman

2. HTML/JS 로 프로토타입 만들고 테스트

3. API 제공자가 Test-bed를 제공

RESTful APIs

Just Docs

• 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

RESTful APIs

Facebook

RESTful APIs

Github

RESTful APIs

With Test-bed

• gAPI

• Iamport

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

https://github.com/SangHakLee/swagger-express-jsdoc

http://10.222.223.145:3000/api-docs/

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

How to use

indent : space 사용

YAML

JSON vs YAML

JSON

YAML