Zi 字媒體

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} 就可以將參數定義成 query string。 將文件產生成網頁的方法可以參考 Aglio Categories: API Blueprint Tags: API-Blueprint 分類 Android AngularJS API Blueprint Chrome Database MySQL DataStructure Editor Vim Firefox Git Hadoop Language Go Java JavaScript jQuery jQueryChart Node.js Vue PHP Laravel ZendFramework Python Mac Network Cisco DLink Juniper Oauth Server Apache Share Unix FreeBSD Linux WebDesign Bootstrap CSS HTML Wordpress Search 搜尋: