使用Blueprint撰寫API文件

稍微記錄一下使用Blueprint作為 API 文件生成工具的小小心得

我自己過去都用 Markdown 在寫文件，但是基於 md 檔本身其實格式過於基本，對於要排版出好閱讀的 API 文件依舊稍嫌不足，Blueprint 本身的概念剛好補足了我對這塊的需求：

撰寫一個 md 檔，然後輸出一個漂亮的 API 文件

前置作業

• Markdown Editor : 不用多作解釋了吧，自己愛用啥就用啥，反正他就只是要寫 MD 檔，我目前是用 VSCode
• Aglio : 主要的渲染器，由npm安裝吧

npm install -g aglio

語法介紹

官方說明文件 要學會怎麼寫文件，首先當然是看寫文件的工具的文件(這啥繞口令)
以下簡單紀錄一下我有用到的入門語法：

metadata

FORMAT:1A
HOST: http://your.domain.com/api

寫在 md 檔最開頭，分別用來記錄使用的 Blueprint 語法版本與 API 的主機位址
後者要寫不寫隨便，有寫的話 Gen 出來的 API 說明會包含完整網址

標題

# 我的API文件

整個 MD 檔第一個 # 會被當成整份文件的標題

群組

# Group 訂單

使用 Group 關鍵字的 # 會被視為 API 群組名稱，可以用此為 API 分類

Resource

## 訂單狀態 [/OrderStatus]
### 查詢訂單狀態 [GET]
使用本API可以查詢到訂單的狀態

使用 ## 說明 [url name] 可以定義一個 API 的進入點(網址)，而使用 ### 說明 [method] 則會定義允許使用的 HttpMethod。 下方可以緊接著寫下詳細的 API 說明，一樣可以使用 + 定義條列式的說明

Response Body

+ Response 200 (applicaiton/json)

	{success:true,message:""}

使用+ Response 狀態碼 (Content-type)來定義回應 需要注意的是如果定義了方法卻沒有定義任何回應會編譯失敗
另外也可以定義 Header

+ Response 200 (applicaiton/json)
	+ Header
		Key : value
	+ Body
		{success:true,message:""}

Request Body

+ Request (applicaiton/json)

	{var1:"0",var2:"1"}

與 Response Body 定義起來的感覺很像

Url Parameter

這個比較複雜一點，如果你的 API 是使用 Http Get，那你的 API 在使用的時候像這樣：

http://your.domain.com/api/getData?id=12345 //常見寫法
http://your.domain.com/api/data/12345       //可以 這很restful

那你的 API 文件撰寫的時候要寫成這樣

## 資料 [/getData{?id}] or [/data/{id}]
### 取得資料 [GET]
+ Parameter
	+ id : `12345` (integer,required) - 資料ID

• 網址的部分要用{}格式化，其中如果是用?帶參數的要特別寫成{?var1,var2}

• 底下要帶一個關鍵字為Parameter的列表

  • 子列表格式意義為

    參數名稱 : 範例值 (資料型態, required || optional ) - 說明
    

  • 只有參數名稱必填，其他欄位都是選填
  • 如果 Parameter 內的參數與網址上沒有定義的格式化字串會編譯失敗

輸出

寫完後使用 aglio 渲染並輸出

aglio -i MD檔名.md -o HTML檔名.html                  //最精簡的寫法
aglio --theme slate -i MD檔名.md -o HTML檔名.html    //輸出深色版本

補充

另一個我覺得寫得很好的教學文件: https://yami.io/api-blueprint-tutorial/