API Blueprint 學習筆記

¶API Blueprint 學習筆記

在開 web service api 文件時，都希望資訊公開、同步更新。所以會有很多工具幫助撰寫並產生 html page。

Aglio 是一種 Api Buleprint 的 Render。

Api Buleprint 是一種 markdown，主要的用途是撰寫 Api 文件
但是大多數(包含官方網站)的教學，總都沒有把文法和 Render 結果貼在一起看(至少是預設的佈景)，讓剛入門的我自己無法學得更快速。

所以，特別寫一篇常用文法的整理。

¶後設資料

並不會被 render 到頁面上。

¶文件版本

FORMAT: 1A

¶文件的 `HOST`

有設定 HOST 的話，下面的 Resource 將會添加上網址的 domain

HOST: https://dwatow.github.io

¶API 名稱&描述

API Name & Description

整份文件第一個h1，寫成# API名稱，用來當作 API 文件的名稱

緊接在API 文件名稱下面的文字，用來當作 API 文件的最初描述

markdown

# Polls

Polls is a simple API allowing consumers to view polls and vote in them.

render result

¶Resource 群組

Resource Groups

一種有接著Group關鍵字的h1，寫成# Group API 群組名稱，用來當 API 群組名稱

緊接在API 群組下面的文字，用來當作 API 群組的描述

markdown

# Group Questions

Resources related to questions in the API.

render result

¶Resource (API 本身)

Resource

官網是用Resource這個字，也許是因為URI，所以稱為Resource，畢竟網址本身可以是各種形式的資源

只要用##就代表要 API 本身。它會定義一組路徑。
再依不同的Actions各別定義要帶資料形式。

markdown

## Question Collection [/questions]

rendered

¶API 動作

Actions

使用### 名字 [動作]可以表示 API 的動作段落

markdown

### List All Questions [GET]

render result

(藍色的部份)

¶很多個 API 動作

每一個Resource都會有不同的動作。
直接用### 名字 [動作]就可以再加一個了。

而且，下面可以直接使用markdown的list語法。
會 render 出條列式的內容

markdown

### Create a New Question [POST]

You may create your own question using this action. It takes a JSON object
containing a question and a collection of answers in the form of choices.

- question (string) - The question
- choices (array[string]) - A collection of choices.

render result

¶Response (JSON)

記錄 Response 形式很多種，用list形式記錄

傳回 200，資料以 JSON 形式呈現。

+ Response 200 (application/json)

Header 的內容是自然 render 生成的

markdown

+ Response 200 (application/json)

        [
            {
                "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
                    }
                ]
            }
        ]

render result

縮起來是這樣

展開是這樣

¶自訂 Response 的 Headers, Body

也可以使用list來自訂 Headers、Body 的 JSON

要注意，Body後面的 JSON 要再多縮一次縮排。

markdown

- Response 201 (application/json)

  - Headers

          Location: /questions/1

  - Body

              {
                  "question": "Favourite programming language?",
                  "published_at": "2014-11-11T08:40:51.620Z",
                  "url": "/questions/1",
                  "choices": [
                      {

render result

¶URI Template

要將 API 網址一部份當變數使用，在此可以使用{變數}的形式，放在 Resource的位址列定義中，稱之為URI Template。

定義 URI Template 時，若有變數，要設定 URI Parameters 區段對變數進行定義。

markdown

## Question [/questions/{question_id}]

render result

¶URI Parameters

用在 URI 的參數描述，使用+ Parameters做list的第一層
通常是用來描述 URL 上的變數。看完整定義

markdown

- Parameters
  - question_id (number) - ID of the Question in the form of an integer
  - question_type(string) - Type of the Question in the form of an String

render result

¶同場加映: Advance Tutorial

這一段進階的教學，大概的內容是在講
如果你在 request 和 response 要放 JSON。
而且希望附上 JSON Schema ，可以考慮使用 MSON (在 + Attributes 下接 list)。

使用 MSON ，就可以使用 Data Structures
另外，還可以使用 Relaiton Types

¶JSON Schema

Action 的 Request 和 Response ，可以描述它們的 Body 結構有相關的 Schema 。
通常使用 JSON Schema 描述 JSON bodies

markdown
在 Response 的 Body 後面加上 + Schema 段落即可。

### Create a New Question [POST]

You may create your own question using this action. It takes a JSON object
containing a question and a collection of answers in the form of choices.

- Request (application/json)

  - Body

          {
            "question": "Favourite language?"
            "choices": [
              "Swift",
              "Objective-C"
            ]
          }

  - Schema

          {
            "$schema": "http://json-schema.org/draft-04/schema#",
            "type": "object",
            "properties": {
              "question": {
                "type": "string"
              },
              "choices": {
                "type": "array",
                "items": {
                  "type": "string"
                },
                "minItems": 2
              }
            }
          }

result

¶Attributes

表示 Request 和 Response 的結構還有另一個方法，就是使用 MSON 撰寫。

MSON 像是 API Blueprint 一樣，可讀性很高，不像 JSON 或 YAML 是給機器讀的

MSON 也允許你描述 API 的資料結構。可以加在 Resource, Action 和 individual requests or responses ，只要加上 + Attributes

注意，自動生成的 JSON Schema 和手寫的並不會完全相同。(可比較上一段手寫的)在這個例子中，minItems 將不會渲染生成。
如果你無法接受，你可以覆寫 schema 。

markdown

當 Attribute 下面那一段成功渲染時，會同時擁有 JSON body 和 JSON Schema 。

### Create a New Question [POST]

You may create your own question using this action. It takes a JSON object
containing a question and a collection of answers in the form of choices.

- Request (application/json)

  - Attributes

    - question: Favourite Language? (required)
    - choices: Swift, `Objective-C` (array, required)

result

¶Data Struct

只要你開始使用 MSON 你可以重複使用某些常用或巢狀的資料結構組合。

可以使用 ## Data Structures 段落。 Attribute 可以引用自己或其它的 Resource 所定義的 data structures 段落名稱

markdown

### List All Questions [GET]

- Response 200 (application/json)

  - Attributes (array[Question])

## Data Structures

### Question

- question: Favourite programming language? (required)
- published_at: `2014-11-11T08:40:51.620Z` (required)
- url: /questions/1 (required)
- choices (array[Choice], required)

### Choice

- choice: JavaScript (required)
- url: /questions/1/choices/1 (required)
- votes: 2048 (number, required)

result

¶Relaiton Types

看不懂作用是什麼。
在此就不誤人子弟了
附上看過的參考資料

## Question [/question/{id}]

### View a Question Detail [GET]

- Relation: self

### Delete a Question [DELETE]

- Relation: delete

## Questions Collection [/questions]

### List All Questions [GET]

- Relation: self

¶MSON 學習筆記

MSON 是一種寫 Markdown Syntax 表示 Object Notation，一種可讀性更高的資料結構表示方式，這個教學學會 MSON 的描述和資料結構表示法

官網提供的 MSON Resource

¶Data structures in MSON

實作注意
這一段介紹的語法，必須寫在 Data structures 段落裡。

下面我們描述了一個 Object 稱為 Person ，它有一個 properties 叫 name。

# Person

- name

使用()宣告 properties 的型別。預設型別是字串。
使用-接上一段文字，當作 properties 的描述。
使用:接上一個值，當作 properties 的值(舉例的值)。

- name: Chris (string) - The Person's name

若 properties 的值，包含下面符號，就要用 back-ticks 包成 code-block。

¶型別

MSON 有 6 種型別可以使用

簡單型別: boolean, string, number
複雜型別: array, enum, object

¶Inheritance

Administrator 繼承 Person

# Administrator (Person)

- role (string) - The administrators role

¶Nesting

Company 裡的 founder 是一個 Person

# Company

- name: Apiary
- founder (Person)

¶Example

用 aglio 實測結果

# Polls API Root [/]

## Retrieve the Entry Point [GET]

- Response 200 (application/json)

  - Attributes

    - Human (Administrator)
      - workHistory (Company)

# Data Structures

# Person

- name: `Spencer-Churchill` (string) - The Person's name

# Administrator (Person)

- role (string) - The administrators role

# Company

- name: Apiary
- founder (Person)
- founded: 2011 (number) - The year in which the company was founded
- address
  - street: 235 Ninth Street
  - city: San Francisco
  - state: California

測試變這樣

¶後記

api blueprint 官網

其它

More advanced Blueprint with MSON

練習頁面成果

發表於 2017-11-14

tags:

{ api }

{ API Doc }

{ Aglio }

¶API Blueprint 學習筆記

¶後設資料

¶文件版本

¶文件的 HOST

¶API 名稱&描述

¶Resource 群組

¶Resource (API 本身)

¶API 動作

¶很多個 API 動作

¶Response (JSON)

¶自訂 Response 的 Headers, Body

¶URI Template

¶URI Parameters

¶同場加映: Advance Tutorial

¶JSON Schema

¶Attributes

¶Data Struct

¶Relaiton Types

¶MSON 學習筆記

¶Data structures in MSON

¶型別

¶Inheritance

¶Nesting

¶Example

¶後記

¶文件的 `HOST`