關於網路那些事...

網路行銷,SEO,網路趨勢,教學文章,網頁設計,生活時事

API Blueprint

API Blueprint

API Bluepirnt 是一個 API 描述語言,可以在開發 API 的過程,使用 markdown 方式快速彙整出 API 文件。

標準的 API Blueprint 是以 .apib 作為副檔名(media 類型為 text/vnd.apiblueprint),當拓展到 Github 上,會直接顯示對應的 Heightlight 。

【用法說明】

這裡直接描述如何建立一個 API 文件流程。

API 描述及版號

首先,在 Blueprint 文件一開始必須定義文件格式

FORMAT: 1A  --> API版本

# My Topic  --> 標題

This is my api description.  --> 描述

Resource Group

透過關鍵字 Group 可以用來將一個相關連的 resource 進行 group 為一個群組,例如

# Group Questions

Resources related to questions in the API.

Resource Collection

在 Resource group 群組內,可以定義 Collection ,這個來源可以用於檢視所有清單,訪問這個資源的 URL 則以方括弧定義在後面,例如:

## Question Collection [/questions]

Actions

API Blueprint 允許你去定義所以有資源的行為(actions)

會透過說明描述,後面再加上使用的方法,例如 Http method

### List All Questions [GET]
### Create New Questions [POST]

Url Parameters

針對請求,通常會需要夾帶參數,參數的定義會透過 Parameters 標題來區別,

接著透過 MSON (Markdown Syntax for Object Notation) 的方式定義參數

開始定義相關參數,交代參數型態及說明

+ Parameters
    + question_id (number) - ID of the Question in the form of an integer
    + number (number, required) - Number of Question number

關於 MSON 與 Json 之間轉換的方式進行對照,可能就會比較清楚

JSON:

{
  "id": 1,
  "title": "我的標題",
  "category": {
    "id": 1,
    "name": "產品名稱"
  },
  "status":0,
  "interest": [
    {
        "id": 1
    }
  ]
}

MSON:

+ id: 1 (number, required) - Id
+ title: `我的標題` (string, required) - 內容描述
+ category
    + id: 1 (number, required) - 分類 Id
    + name: `名稱` (string, required) - 內容說明
+ status: 0(enum)
    + 0 - 未進行
    + 1 - 進行中
    + 2 - 已完成
+ interest
    + (object)
        + id: 1 (number, required) - Id

可參考 blueprint 官方 MSON 說明

Response

當我們請求之後,會取得一個回應,回應的內容會透過 +, *, - 的方式來產生 list 格式,並且開始說明 response 的狀態碼,例如:

GET

+ Response 200 (application/json)
    + Attributes (Server response)

POST

+ Response 201 (application/json)

DELTE

+ Response 204 (application/json)

POST and get Headers

+ Response 200 (application/json)
    + Attributes (Server response)
    + Headers
        Authentication: Bearer JWT

Response Attributes

另外,可以透過 Attributes 來描述返回的 body json 內容進行說明

例如

A Question object has the following attributes:

+ question
+ published_at - An ISO8601 date when the question was published.
+ url
+ choices - An array of Choice objects.

Response Detail

接著就是關於這個 reponse 的 json body 回應示意

   [
        {
            "question": "Favourite programming language?",
            "published_at": "2014-11-11T08:40:51.620Z",
            "url": "/questions/1",
            "choices": [
                {
                    "choice": "Swift",
                    "url": "/questions/1/choices/1",
                    "votes": 2048
                }, {
                    "choice": "Python",
                    "url": "/questions/1/choices/2",
                    "votes": 1024
                }, {
                    "choice": "Objective-C",
                    "url": "/questions/1/choices/3",
                    "votes": 512
                }, {
                    "choice": "Ruby",
                    "url": "/questions/1/choices/4",
                    "votes": 256
                }
            ]
        }
    ]

推薦

通常可以透過 aglio 來render 出 HTML 格式

例如,透過以下語法可以轉出為html

aglio -i myapi.apib -o myapi.html

VS Code 則可以安裝拓展:API Blurprint Viewer, API Elements extension, Blueprint


如果這篇文章對你有幫助,請在這裡點個讚



最新文章推薦