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)
- 如何同時使用兩個臉書帳號?用App Cloner以方便第二個帳號的自動登入 (1則留言, 2016/03/28)
- Toodledo官方版Android App終於推出了 (0則留言, 2014/01/28)
- JSP快速產生Excel內容的方法 (0則留言, 2015/07/15)
- 將Windows 10 Modern App釘選到桌面與快速執行的步驟 (0則留言, 2015/08/12)
- 用App Launcher建立Windows 7的桌面工具列 (1則留言, 2010/11/11)
- 快速產生HTML網頁格式的速記語法:Markdown (0則留言, 2013/09/20)
- [Android Studio #11] 取出設定好的App版本號碼 (0則留言, 2015/05/13)
- 如何將Markdown文件轉換成HTML? (1則留言, 2011/03/06)
- 以iPad做為WordPress網誌書寫設備的方便Apps (0則留言, 2012/03/04)
- [Android] 彙整數萬個免費桌布與電話鈴聲的App:Zedge,展現個人化的第一步 (0則留言, 2013/08/17)
- 使用WebInspect 10偵測網站系統弱點的簡單步驟 (0則留言, 2013/10/27)
- Dropbox App 1.5增加了自動上傳照片檔的功能 (0則留言, 2012/06/16)