API Blueprint 學習筆記

  1. API Blueprint 學習筆記
  2. 後設資料
    1. 文件版本
    2. 文件的 HOST
  3. API 名稱&描述
  4. Resource 群組
  5. Resource (API 本身)
    1. API 動作
    2. 很多個 API 動作
      1. Response (JSON)
      2. 自訂 Response 的 Headers, Body
  6. URI Template
    1. URI Parameters
  7. 同場加映: Advance Tutorial
  8. JSON Schema
  9. Attributes
  10. Data Struct
  11. Relaiton Types
  12. MSON 學習筆記
  13. Data structures in MSON
    1. 型別
    2. Inheritance
    3. Nesting
  14. Example
  15. 後記

API Blueprint 學習筆記

在開 web service api 文件時,都希望資訊公開、同步更新。所以會有很多工具幫助撰寫並產生 html page。

Aglio 是 一種 Api Buleprint 的 Render。

Api Buleprint 是一種 markdown,主要的用途是撰寫 Api 文件
但是大多數(包含官方網站)的教學,總都沒有把文法和 Render 結果貼在一起看(至少是預設的佈景),讓剛入門的我自己無法學得更快速。

所以,特別寫一篇常用文法的整理。

後設資料

並不會被 render 到頁面上。

文件版本

FORMAT: 1A

文件的 HOST

有設定 HOST 的話,下面的 Resource 將會添加上網址的 domain

HOST: https://dwatow.github.io

API 名稱&描述

API Name & Description

整份文件第一個h1,寫成# API名稱,用來當作 API 文件的名稱

緊接在API 文件名稱下面的文字,用來當作 API 文件的最初描述

markdown

# Polls

Polls is a simple API allowing consumers to view polls and vote in them.

render result

Resource 群組

Resource Groups

一種有接著Group關鍵字的h1,寫成# Group API 群組名稱,用來當 API 群組名稱

緊接在API 群組下面的文字,用來當作 API 群組 的描述

markdown

# Group Questions

Resources related to questions in the API.

render result

Resource (API 本身)

Resource

官網是用Resource這個字,也許是因為URI,所以稱為Resource,畢竟網址本身可以是各種形式的資源

只要用##就代表要 API 本身。它會定義一組路徑。
再依不同的Actions各別定義要帶資料形式。

markdown

## Question Collection [/questions]

rendered

API 動作

Actions

使用### 名字 [動作]可以表示 API 的動作段落

markdown

### List All Questions [GET]

render result

(藍色的部份)

很多個 API 動作

每一個Resource都會有不同的動作。
直接用### 名字 [動作]就可以再加一個了。

而且,下面可以直接使用markdownlist語法。
會 render 出條列式的內容

markdown

### Create a New Question [POST]

You may create your own question using this action. It takes a JSON object
containing a question and a collection of answers in the form of choices.

- question (string) - The question
- choices (array[string]) - A collection of choices.

render result

Response (JSON)

記錄 Response 形式很多種,用list形式記錄

傳回 200,資料以 JSON 形式呈現。

+ Response 200 (application/json)

Header 的內容是自然 render 生成的

markdown

+ Response 200 (application/json)

[
{
"question": "Favourite programming language?",
"published_at": "2014-11-11T08:40:51.620Z",
"url": "/questions/1",
"choices": [
{
"choice": "Swift",
"url": "/questions/1/choices/1",
"votes": 2048
}, {
"choice": "Python",
"url": "/questions/1/choices/2",
"votes": 1024
}, {
"choice": "Objective-C",
"url": "/questions/1/choices/3",
"votes": 512
}, {
"choice": "Ruby",
"url": "/questions/1/choices/4",
"votes": 256
}
]
}
]

render result

縮起來是這樣

展開是這樣

自訂 Response 的 Headers, Body

也可以使用list來自訂 Headers、Body 的 JSON

要注意,Body後面的 JSON 要再多縮一次縮排。

markdown

- Response 201 (application/json)

- Headers

Location: /questions/1

- Body

{
"question": "Favourite programming language?",
"published_at": "2014-11-11T08:40:51.620Z",
"url": "/questions/1",
"choices": [
{

render result

URI Template

要將 API 網址一部份當變數使用,在此可以使用{變數}的形式,放在 Resource的位址列定義中,稱之為URI Template

定義 URI Template 時,若有變數,要設定 URI Parameters 區段對變數進行定義。

markdown

## Question [/questions/{question_id}]

render result

URI Parameters

用在 URI 的參數描述,使用+ Parameterslist的第一層
通常是用來描述 URL 上的變數。看完整定義

markdown

- Parameters
- question_id (number) - ID of the Question in the form of an integer
- question_type(string) - Type of the Question in the form of an String

render result

同場加映: Advance Tutorial

這一段進階的教學,大概的內容是在講
如果你在 requestresponse 要放 JSON
而且希望附上 JSON Schema ,可以考慮使用 MSON (在 + Attributes 下接 list)。

使用 MSON ,就可以使用 Data Structures
另外,還可以使用 Relaiton Types

JSON Schema

ActionRequestResponse ,可以描述它們的 Body 結構有相關的 Schema
通常使用 JSON Schema 描述 JSON bodies

markdown
ResponseBody 後面加上 + Schema 段落即可。

### Create a New Question [POST]

You may create your own question using this action. It takes a JSON object
containing a question and a collection of answers in the form of choices.

- Request (application/json)

- Body

{
"question": "Favourite language?"
"choices": [
"Swift",
"Objective-C"
]
}

- Schema

{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"question": {
"type": "string"
},
"choices": {
"type": "array",
"items": {
"type": "string"
},
"minItems": 2
}
}
}

result

Attributes

表示 RequestResponse 的結構還有另一個方法,就是使用 MSON 撰寫。

MSON 像是 API Blueprint 一樣,可讀性很高,不像 JSONYAML 是給機器讀的

MSON 也允許你描述 API 的資料結構。可以加在 Resource, Action 和 individual requests or responses , 只要加上 + Attributes

注意,自動生成的 JSON Schema 和手寫的並不會完全相同。(可比較上一段手寫的)在這個例子中,minItems 將不會渲染生成。
如果你無法接受,你可以覆寫 schema

markdown

Attribute 下面那一段成功渲染時,會同時擁有 JSON bodyJSON Schema

### Create a New Question [POST]

You may create your own question using this action. It takes a JSON object
containing a question and a collection of answers in the form of choices.

- Request (application/json)

- Attributes

- question: Favourite Language? (required)
- choices: Swift, `Objective-C` (array, required)

result

Data Struct

只要你開始使用 MSON 你可以重複使用某些常用或巢狀的資料結構組合。

可以使用 ## Data Structures 段落。 Attribute 可以引用自己或其它的 Resource 所定義的 data structures 段落名稱

markdown

### List All Questions [GET]

- Response 200 (application/json)

- Attributes (array[Question])

## Data Structures

### Question

- question: Favourite programming language? (required)
- published_at: `2014-11-11T08:40:51.620Z` (required)
- url: /questions/1 (required)
- choices (array[Choice], required)

### Choice

- choice: JavaScript (required)
- url: /questions/1/choices/1 (required)
- votes: 2048 (number, required)

result

Relaiton Types

看不懂作用是什麼。
在此就不誤人子弟了
附上看過的參考資料

## Question [/question/{id}]

### View a Question Detail [GET]

- Relation: self

### Delete a Question [DELETE]

- Relation: delete

## Questions Collection [/questions]

### List All Questions [GET]

- Relation: self

MSON 學習筆記

MSON 是一種寫 Markdown Syntax 表示 Object Notation,一種可讀性更高的資料結構表示方式,這個教學學會 MSON 的描述和資料結構表示法

官網提供的 MSON Resource

Data structures in MSON

實作注意
這一段介紹的語法,必須寫在 Data structures 段落裡。

下面我們描述了一個 Object 稱為 Person ,它有一個 propertiesname

# Person

- name

使用()宣告 properties 的型別。預設型別是字串。
使用-接上一段文字,當作 properties 的描述。
使用:接上一個值,當作 properties 的值(舉例的值)。

- name: Chris (string) - The Person's name

properties 的值,包含下面符號,就要用 back-ticks 包成 code-block

型別

MSON 有 6 種型別可以使用

  • 簡單型別: boolean, string, number
  • 複雜型別: array, enum, object

Inheritance

Administrator 繼承 Person

# Administrator (Person)

- role (string) - The administrators role

Nesting

Company 裡的 founder 是一個 Person

# Company

- name: Apiary
- founder (Person)

Example

aglio 實測結果

# Polls API Root [/]

## Retrieve the Entry Point [GET]

- Response 200 (application/json)

- Attributes

- Human (Administrator)
- workHistory (Company)

# Data Structures

# Person

- name: `Spencer-Churchill` (string) - The Person's name

# Administrator (Person)

- role (string) - The administrators role

# Company

- name: Apiary
- founder (Person)
- founded: 2011 (number) - The year in which the company was founded
- address
- street: 235 Ninth Street
- city: San Francisco
- state: California

測試變這樣

後記

api blueprint 官網

其它

練習頁面成果