撰寫API規格文件的利器：API Blueprint與aglio

API Blueprint是一個用來產生RESTful Web Services API規格的樣板語言，只要依它定義的格式寫好Markdown格式的文字檔，再使用輔助工具（有很多個，本文介紹的是aglio）就能產生標準、統一的API文件。相較於類似功能的Swagger或RAML，API Blueprint的最大優點就是撰寫容易快速，如果原本已經具有Markdown的使用經驗，那更是能在最短時間內就掌握好。

API Blurprint的基本格式範例如下：

FORMAT: 1.0
# API名稱

API說明

## 說明重點1

## 說明重點2

# Group 資源群組以 Group 開頭

## 資源 [/URI]

### 動作 [GET]

* Parameters
    * 參數1: `範例值` (required, 格式) - 參數說明
    * 參數2: `範例值` (optional, 格式) - 參數說明

* Response 200 (application/json)

        { "code": "OK", "message": "success" }

* Response 404 (application/json)

        { "code": "NOT_FOUND", "message": "No data" }

### 動作 [POST]

內容格式同 GET

### 動作 [DELETE]

內容格式同 GET

重點說明

• 群組分類以 Group 開頭
• Response裡的傳回範例以8個空白或兩個 Tab 開頭
• 如果有多個API或多人同時撰寫時，可以用引入的方法把一個檔案拆成幾個檔案，如：

# Group 1. 城市資料
<!-- include(CITY.md) -->

# Group 2. 氣象資料 
<!-- include(WEATHER1.md) -->
<!-- include(WEATHER2.md) -->

將Markdown轉換為HTML

接著用 aglio 將Markdown格式的文字檔案轉換成HTML。aglio是Node.js的模組，安裝好Node.js後再用下列指定安裝aglio:

npm install -g aglio

執行轉換的命令：

aglio -i Markdown檔名  -o 產生的HTML檔名  [選項]

• 選項：只執行aglio會列出所有選項的說明
• 例如用 --theme-variables flatly 可以變更Default樣式為flatly樣式

範例

FORMAT: 1.0

# 城市與氣象資訊Web Services API

* 這是使用API blueprint撰寫的示範文件
* 由 [GlobalWeather Web Service](http://www.webservicex.net/globalweather.asmx?op=GetWeather) 取得相關資料

# Group 1. 城市資料

* 這是使用API blueprint撰寫的示範文件
* 由 [GlobalWeather Web Service](http://www.webservicex.net/globalweather.asmx?op=GetWeather) 取得氣象資料

## 依國名取回城市名 [/globalweather.asmx/GetCitiesByCountry?CountryName={CountryName}]

### 取回城市名 [GET]

* Parameters
    * CountryName: `Taiwan` (required, String) - 國名

* Response 200 (text/xml)

        <string xmlns="http://www.webserviceX.NET">
          <NewDataSet>
           <Table>
             <Country>Taiwan</Country>
             <City>Kangshan Tw-Afb</City>
           </Table>
           <Table>
             <Country>Taiwan</Country>
             <City>Chinmem / Shatou Air Force Base</City>
           </Table>
         </NewDataSet>
        </string>

# Group 2. 氣象資料 

* 這是使用API blueprint撰寫的示範文件
* 由 [GlobalWeather Web Service](http://www.webservicex.net/globalweather.asmx?op=GetWeather) 取得氣象資料

## 依城市名稱取回氣象 [/globalweather.asmx/GetWeather?CityName={CityName}&CountryName={CountryName}]

### 取回氣象資料 [GET]

* Parameters
    * CityName: `Taipei` (required, String) - 城市名
    * CountryName: `Taiwan` (optional, String) - 國名

* Response 200 (text/xml)

        <string xmlns="http://www.webserviceX.NET">Data Not Found</string>

＃＃

您可能也會有興趣的類似文章

• 使用IntelliJ IDEA 12的Android UI Designer輕鬆寫Android App (1則留言, 2012/08/09)
• 使用Google API與建立憑證的步驟 (0則留言, 2016/02/21)
• 使用ModernMix將Windows 8 App變成桌面視窗 (0則留言, 2013/03/25)
• [Obs＃105] Obsidian外掛 Local REST API 提供外部整合服務 (0則留言, 2022/11/06)
• 如何同時使用兩個臉書帳號？用App Cloner以方便第二個帳號的自動登入 (1則留言, 2016/03/28)
• Toodledo官方版Android App終於推出了 (0則留言, 2014/01/28)
• 將Windows 10 Modern App釘選到桌面與快速執行的步驟 (0則留言, 2015/08/12)
• 用App Launcher建立Windows 7的桌面工具列 (1則留言, 2010/11/11)
• JSP快速產生Excel內容的方法 (0則留言, 2015/07/15)
• [Android Studio #11] 取出設定好的App版本號碼 (0則留言, 2015/05/13)
• 國人自製Android App：懶人外掛：裝LINE必備，聊天泡泡方便無比 (0則留言, 2017/03/22)
• 04. 使用第三方Android模擬器來執行Android/Flutter App (0則留言, 2019/09/27)
• [Android] 彙整數萬個免費桌布與電話鈴聲的App：Zedge，展現個人化的第一步 (0則留言, 2013/08/17)
• 使用WebInspect 10偵測網站系統弱點的簡單步驟 (0則留言, 2013/10/27)
• Obsidian常見問題008：如何將網頁表格快速轉換為Markdown表格 (0則留言, 2022/12/09)