Getting Started with API Blueprint

API Blueprint 是一種基於 markdown 加上一些變形的方式去撰寫 API 文件的規範，官網上面也有詳列許多相關操作的工具，例如將文件 render 成 HTML、文件的 parser 等等。

完整 Spec 可以參考 官方文件

Metadata

Metadata 是用來定義一些隱性的資料，格式為 Key: Value。

FORMAT 是用來標註 API Blueprint 的版本。

FORMAT: 1A
HOST: https://blog.johsnonlu.org

API Name and Description

跟 Markdown 相同，# 符號會被定義成標題，而 第一個標題就會是你的 API 文件名稱。

# 引渡西方系統

這是一個超猛的成仙系統，使用下去就成仙。

Resource Groups

Resource Groups 是建立一個資源群組，透過 Group 關鍵字來控制。

白話一點就是可以把 Resource Groups 當成分類（Category）來看會比較好理解，當 render 成網頁以後會根據不同的 Group 產生不同的區塊。

# Group 成仙用的 API

成仙用的 API。

# Group 打第三方的 API

打第三方的 API

Resource and Action

Resource 可以當成是 API 本身或者文件標題，如果是 API 的話，標題後面可以使用 [/URI] 的方式定義 URI。

而一個 Resource 底下會有許多 Action，每個 Action 也都會有 至少一種 的 Response，可以用 Response 關鍵字搭配 Http status code 定義 Action 的回傳格式。

另外，由於一個 Action 會有多個 Response，所以必須用無序清單符號 + 定義。

## God [/god]

### 列出所有神佛 [GET]

這個 API 會列出所有神佛。

+ Response 200 (application/json)

        [
            {
                "name": "媽祖"
            },
            {
                "name": "佛祖"
            }
        ]

也可以個別定義 Headers 內容

## God [/god]

### 列出所有神佛 [GET]

+ Response 200 (application/json)

    + Headers

            X-My-Message-Header: 42

    + Body

            [
                {
                    "name": "媽祖"
                },
                {
                    "name": "佛祖"
                }
            ]

URI Template and Parameters

API 少不了傳遞參數，利用 {var} 定義資源會用到的變數，透過 Parameters 描述參數的類型。

## God [/god/{id}]

+ Parameters
    + id: 2 (number, required) - 代入神明ID

### 神佛資訊 [GET]

+ Response 200

如果 API 不是 RESTful 的話，使用 {?var,name,...} 就可以將參數定義成 query string。

將文件產生成網頁的方法可以參考 Aglio