API Blueprint

API Blueprint

API Bluepirnt 是一個 API 描述語言，可以在開發 API 的過程，使用 markdown 方式快速彙整出 API 文件。

標準的 API Blueprint 是以 .apib 作為副檔名（media 類型為 text/vnd.apiblueprint)，當拓展到 Github 上，會直接顯示對應的 Heightlight 。

【用法說明】

這裡直接描述如何建立一個 API 文件流程。

API 描述及版號

首先，在 Blueprint 文件一開始必須定義文件格式

FORMAT: 1A  --> API版本

# My Topic  --> 標題

This is my api description.  --> 描述

Resource Group

透過關鍵字 Group 可以用來將一個相關連的 resource 進行 group 為一個群組，例如

# Group Questions

Resources related to questions in the API.

Resource Collection

在 Resource group 群組內，可以定義 Collection ，這個來源可以用於檢視所有清單，訪問這個資源的 URL 則以方括弧定義在後面，例如：

## Question Collection [/questions]

Actions

API Blueprint 允許你去定義所以有資源的行為(actions)

會透過說明描述，後面再加上使用的方法，例如 Http method

### List All Questions [GET]

### Create New Questions [POST]

Url Parameters

針對請求，通常會需要夾帶參數，參數的定義會透過 Parameters 標題來區別，

接著透過 MSON (Markdown Syntax for Object Notation) 的方式定義參數

開始定義相關參數，交代參數型態及說明

+ Parameters
    + question_id (number) - ID of the Question in the form of an integer
    + number (number, required) - Number of Question number

關於 MSON 與 Json 之間轉換的方式進行對照，可能就會比較清楚

JSON:

{
  "id": 1,
  "title": "我的標題",
  "category": {
    "id": 1,
    "name": "產品名稱"
  },
  "status":0,
  "interest": [
  	{
  		"id": 1
  	}
  ]
}

MSON:

+ id: 1 (number, required) - Id
+ title: `我的標題` (string, required) - 內容描述
+ category
	+ id: 1 (number, required) - 分類 Id
	+ name: `名稱` (string, required) - 內容說明
+ status: 0(enum)
	+ 0 - 未進行
	+ 1 - 進行中
	+ 2 - 已完成
+ interest
	+ (object)
		+ id: 1 (number, required) - Id

可參考 blueprint 官方 MSON 說明

Response

當我們請求之後，會取得一個回應，回應的內容會透過 +, *, - 的方式來產生 list 格式，並且開始說明 response 的狀態碼，例如：

GET

+ Response 200 (application/json)
	+ Attributes (Server response)

POST

+ Response 201 (application/json)

DELTE

+ Response 204 (application/json)

POST and get Headers

+ Response 200 (application/json)
	+ Attributes (Server response)
	+ Headers
		Authentication: Bearer JWT

Response Attributes

另外，可以透過 Attributes 來描述返回的 body json 內容進行說明

例如

A Question object has the following attributes:

+ question
+ published_at - An ISO8601 date when the question was published.
+ url
+ choices - An array of Choice objects.

Response Detail

接著就是關於這個 reponse 的 json body 回應示意

       [
            {
                "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
                    }
                ]
            }
        ]

推薦

通常可以透過 aglio 來render 出 HTML 格式

例如，透過以下語法可以轉出為html

aglio -i myapi.apib -o myapi.html

VS Code 則可以安裝拓展：API Blurprint Viewer, API Elements extension, Blueprint