API Blueprint - API 文件規範的三大領頭之一

1. API blueprint - API 文
件規範的三大領頭之一
Kewang

2. 2
Live DEMO
https://github.com/kewang/apiblueprint-test

3. 3
API Blueprint (Markdown-like)
# Group Questions
Resources related to questions in the API.
## Question Collection [/questions]
### List All Questions [GET]
+ Response 200 (application/json)
[
{
"question": "Favourite programming language?",
"published_at": "2014-11-11T08:40:51.620Z",
"choices": [
{
"choice": "Swift",
"url": "/questions/1/choices/1",
"votes": 2048
}
]
}
]

4. 4
RAML (YAML-like)
/questions:
displayName: Resources related to questions in the API.
get:
description: List All Questions
responses:
200:
body:
application/json:
type: array
example: |
[
{
"question": "Favourite programming language?",
"published_at": "2014-11-11T08:40:51.620Z",
"choices": [
{
"choice": "Swift",
"url": "/questions/1/choices/1",
"votes": 2048
}
]
}
]

5. 5
Swagger (YAML-like)
paths:
/questions:
get:
responses:
'200':
description: OK
examples:
application/json:
- question: Favourite programming language?
published_at: '2014-11-11T08:40:51.620Z'
choices:
- choice: Swift
url: /questions/1/choices/1
votes: 2048
summary: List All Questions
tags:
- Questions
produces:
- application/json

6. 6
DX
developer experience

7. 7
API Blueprint
● 文件為導向的 API 描述語言
● 以 Markdown 語法為主
● apiary 的主體

8. 8
相關工具
● Apiary ：整合環境
– sample code 、 REST client 、 mock server 、 renderer
– 本機執行： Apiary CLI
● aglio： renderer
● Drakov： mock server
● 其他： curl, Postman, Paw

9. 9
aglio - renderer
●
規格修改後可即時更新
● 可產生一頁式的 API 網頁
● 可產生 server 直接連線
● 各種 theme ，包括兩欄式及三欄式
● 可自訂 CSS / Less
● 有 npm library

10. 10
Drakov – mock server
●
規格修改後可即時更新
● 可模擬 server 執行時間
● 支援 CORS
● 支援 HTTPS
● 支援 Access-Control-Allow-Methods 及 Access-
Control-Allow-Headers
● 有 npm library

11. 11
相關工具
● Apiary ：整合環境
– sample code 、 REST client 、 mock server 、 renderer
– 本機執行： Apiary CLI
● aglio： renderer
● Drakov： mock server
● 其他： curl, Postman, Paw

12. 12
Live DEMO

13. 13
番外篇

14. 14
MSON
Markdown Syntax for Object Notation

15. 15
MSON起源
●
滿足人類易讀且機器易讀
● DSL非常適合做為
● 從 API Blueprint 衍生而來
# Contact
- name: John Appleseed
- email: john@apple.com (required)

16. 16
範例：公文

17. 17
範例：公文
## 公文
### 函 三竹資訊
* address: " 台北市中山區帥哥路 2 號 "
* contact: "Kewang"
* phone: "02-23456789"
* fax: "02-23456780"
* email: "service@mitake.com.tw"
### 受文者 王慕群
* address: 美國白宮
* date: 106/02/03 (date)
* post-number-name: 三竹
* post-number-number: 20170726001
* level: secret
### 主旨 想睡覺的方式有幾種？
#### 說明
1. 因為想睡覺
2. 所以想睡覺

18. 18