API blueprint說明書

時間 2019-12-07

標籤 api blueprint 說明書简体版

原文原文鏈接

html

1. API blueprint

git

1. API blueprint

1.1. 概要

1.2. Tutorial

1.2.1. format

FORMAT: 1A

# Polls

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

這裏展現一些列表：
* list item 1
* list item 2
* list item 3

FORMAT 關鍵字指示 API blueprint 的版本是 1A.github

第一個標題是 API 的名字，上面是 Polls，後面是 API 的描述, 描述中可使用 markdown 語法。web

1.2.2. Resource Groups

在標題行的開頭使用 Group 關鍵字表示相關聯的一組資源。npm

# Group Questions

Resources related to questions in the API.

1.2.3. Resource

定義在 Resource Group 下面, 在標題末尾的方括號內填寫資源的 URI。json

## Questions Collection [/questions]

1.2.4. Actions

定義在 Resource 下面，標題後的方括號內填寫動做( HTTP 方法).api

### List All Questions [GET]

一個 Action 至少要有一個 Response，Response 包含一個狀態碼，響應體可選。 Response 是一個列表項，列表項可使用 +, * 或 -.bash

+ 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
                    }
                ]
            }
        ]

狀態碼後面的 media 類型會生成一個 Content-Type http 頭，這個不是必須指定的。 response 的響應體縮進8個空格或者2個tab。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.

請求時使用 JSON 格式：

+ Request (application/json)

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

返回 201 狀態碼以及 http 頭和 body:

+ 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": [
                        {
                            "choice": "Swift",
                            "url": "/questions/1/choices/1",
                            "votes": 0
                        }, {
                            "choice": "Python",
                            "url": "/questions/1/choices/2",
                            "votes": 0
                        }, {
                            "choice": "Objective-C",
                            "url": "/questions/1/choices/3",
                            "votes": 0
                        }, {
                            "choice": "Ruby",
                            "url": "/questions/1/choices/4",
                            "votes": 0
                        }
                    ]
                }

下一個資源是 "Question"，表示一個單獨的問題：

## Question [/questions/{question_id}]

1.2.5. URI Template

URI 中使用變量，好比上例中的 question_id。

1.2.6. URI Parameters

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

1.2.7. actions

### View a Questions Detail [GET]

+ 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
                    }
                ]
            }

1.2.8. Response without a body

### Delete [DELETE]

+ Response 204

1.3. API Blueprint Language

FROM https://github.com/apiaryio/api-blueprint/blob/master/API%20Blueprint%20Specification.md

API blueprint 是一個面向文檔的web API設計語言。基於 Markdown 語法。

一個 API blueprint 文檔使用所有或部分 Markdown 文檔來描述 web API. 文檔按結構分紅幾個邏輯章節。

文檔結構：

1.3.1. Blueprint section

section 表示 API 藍圖的邏輯單元，好比一個API預覽，一組資源或者一個資源定義。

一般，section使用一個markdown實體中的關鍵字來定義，根據section的類型，關鍵字能夠做爲一個markdown標題或者一個列表項。

section定義中能夠還會包含額外的變量組件，好比標識符或者額外的修飾符。

NOTE: 有兩個特殊的section是根據他們的位置而不是關鍵字來識別的：Metadata section 和 api名稱和簡介部分。

例子：標題形式的section

# <keyword>

 ...

# <keyword>

 ...

或者：

<keyword>
=========

...

<keyword>
=========

...

例子：列表形式的section:

+ <keyword>

 ...

+ <keyword>

 ...

除了 +，還可使用 - 或者 *:

* <keyword>

...

- <keyword>

...

1.3.1.1. section結構

一般，一個由關鍵字定義的section包含標識符(name)，描述，嵌套的section，或者特定格式的內容。

例子：標題形式：

# <keyword> <identifier>

<description>

<specific content>

<nested sections>

例子：列表形式：

+ <keyword> <identifier>

    <description>

    <specific content>

    <nested sections>

1.3.1.2. 關鍵字

section中的關鍵字有如下幾個

標題關鍵字

Group
Data Structures
HTTP methods(e.g. GET, POST, PUT, DELETE...)
URI模板(e.g. /resource/{id})
HTTP方法和URI模板組合(e.g. GET /resource/{id})

列表關鍵字

Request
Response
Body
Schema
Model
Header & Headers
Parameter & Parameters
Values
Attribute & Attributes
Relation

NOTE: 儘可能避免在其餘 markdown 標題或者列表中使用這些關鍵字。 NOTE: 除了HTTP方法關鍵字外其餘關鍵字是大小寫敏感的。

1.3.1.3. 標識符

section中可能或者必須包含一個標識符。標識符是任意非空字符的組合，除了 [, ], (, ) 和換行符。標識符中不能包含關鍵字。

例子：

Adam's Message 42
my-awesome-message_2

1.3.1.4. 描述

描述是section定義後面的任意的markdown格式的內容。

描述中能夠適應任意的markdown標題或者列表，只有不與保留關鍵字衝突便可。

1.3.1.5. 嵌套的section

根據section的類型來嵌套section，好比增長標題級別或者增長列表項的縮進。

section開始處和緊跟着的下一個同等級的section之間的任意內容都屬於該section.

例子：嵌套的標題形式的section:

# <section definition>

 ...

## <nested section definition>

 ...

例子：嵌套的列表形式的section:

+ <section definition>

     ...

    + <nested section definition>

     ...

1.3.2. section參考

1.3.2.1. 摘要

1.3.2.1.1. Named section

定義爲一個關鍵字緊跟着可選的名稱：

# <keyword> <identifier>
+ <keyword> <identifier>

這是基本形式，由標識符、描述、嵌套section或者特定格式的內容組成。

例子：

# <keyword> Section Name
This the `Section Name` description.

- one
- **two**
- three

<nested sections> |  <formatted content>

1.3.2.1.2. Asset section

僅由關鍵字來定義。

+ <keyword>

API blueprint中原子數據的基本section。內容是格式化的代碼塊。

例子：

+ <keyword>

        {
            "message": "Hello"
        }

例子：Fenced code blocks

+ <keyword>

    ```
    {
        "message": "Hello"
    }
    ```

1.3.2.1.3. Payload section

由一個在列表項中的關鍵字來定義，關鍵字後能夠跟一個標識符，還可能包含由括號括起來的media類型。

+ <keyword> <identifier> (<media type>)

表示HTTP請求或響應的負載信息。由可選的http頭形式的meta信息和可選的http body形式的內容組成。

此外，負載(payload)還包含它自己的描述，消息體屬性的描述，消息體驗證模式的描述。

負載可能與其media類型相關聯。負載的media類型表示以HTTP的Content-Type頭形式接收或發送的元數據。指定一個負載時應包含嵌套的Body section.

這個section應包含如下嵌套section中至少一個：

0-1 Headers section
0-1 Attributes section
0-1 Body section
0-1 Schema section

若是沒有嵌套的section，負載的內容會被考慮做爲Body section.

Body, Schema 和 Attributes section的關係

每一個body, schema和attributes section描述一個信息負載的body.這些描述應該是一致的，相互不能衝突。當有多個body描述時應該按照如下優先級：

對於解析消息體模式
1. Schema section
2. Attributes section
3. Body section
對於解析消息體例子
1. Body section
2. Attributes section
3. Schema section

引用

除了提供payload section的內容外，還能夠引用一個model payload section:

[<identifier>][]

例子：

+ <keyword> Payload Name (application/json)

    This the `Payload Name` description.

    + Headers

     ...

    + Body

     ...

    + Schema

    ...

引用model payload:

+ <keyword> Payload Name

    [Resource model identifier][]

1.3.3. section基礎

1.3.3.1. Metadata section

鍵值對。鍵值之間用 : 分隔。每一個鍵值對一行。在文檔開頭定義，結束於第一個不能解析爲鍵值對的markdown元素。

元數據的鍵值對是做用於工具的，關於支持的鍵的列表須要查詢相關工具的文檔。

例子：

FORMAT: 1A
HOST: http://blog.acme.com

1.3.3.2. API 名稱和概覽部分

第一個markdown標題會被當作名稱和概覽的部分，除非這個標題表示其餘的section定義。（表示這個section無關緊要）

例子：

# Basic ACME Blog API
Welcome to the **ACME Blog** API. This API provides access to the **ACME
Blog** service.

1.3.3.3. Resource group section

以 Group 關鍵字開頭，後面跟組的名稱。

# Group <identifier>

表明一組資源，可能會包含一個或多個嵌套的Resource section.

例子：

# Group Blog Posts

## Resource 1 [/resource1]

 ...

# Group Authors
Resources in this groups are related to **ACME Blog** authors.

## Resource 2 [/resource2]

 ...

1.3.3.4. Resource section

URI模板形式：

# <URI template>

或者 URI 模板前加上標識符：

# <identifier> [<URI template>]

或者 URI 模板前添加 HTTP 方法：

# <HTTP request method> <URI template>

或者標識符加 http 方法加uri模板：

# <identifier> [<HTTP request method> <URI template>]

API 資源由它的URI指定，或者由匹配URI模板的資源集合指定。

這個section至少應包含一個嵌套的 Action section，可能包含如下嵌套的 section:

0-1 URI parameters section 在 Resource section範圍內定義的URI模板適用於任何嵌套的action section，除非爲Action定義了模板。
0-1 Attribute section 在 Resource section 範圍內定義的屬性表示資源屬性。若是資源使用一個名字定義屬性，那麼這些屬性可能引用了屬性section。
0-1 Model section
額外的 Action section

例子：

# Blog Posts [/posts/{id}]
Resource representing **ACME Blog** posts.

# /posts/{id}

# GET /posts/{id}

1.3.3.5. Resource model section

使用 Model 關鍵字定義，後面可跟media類型。

+ Model (<media type>)

在這個section中定義的payload可使用父section的標識符在任意響應或請求部分引用。

例子：

# My Resource [/resource]

+ Model (text/plain)

        Hello World

## Retrieve My Resource [GET]

+ Response 200

    [My Resource][]

1.3.3.6. Schema section

+ Schema

爲http消息體指定一個有效的模式。

例子：

下面的例子使用Body提供一個application/json的例子，使用Schema提供一個JSON模式描述全部可能的有效的payload.

## Retrieve a Message [GET]

+ Response 200 (application/json)
    + Body

            {"message": "Hello world!"}

    + Schema

            {
                "$schema": "http://json-schema.org/draft-04/schema#",
                "type": "object",
                "properties": {
                    "message": {
                        "type": "string"
                    }
                }
            }

1.3.3.7. Action section

使用http請求方法定義：

## <HTTP request method>

或者http方法前添加action標識符：

## <identifier> [<HTTP request method>]

或者標識符+請求方法+uri模板：

## <identifier> [<HTTP request method> <URI template>]

至少定義一個HTTP事務，可能有多個事務例子。

能夠包含一個嵌套的URI參數部分，做用域僅在相應的action內。

能夠包含一個嵌套的參數部分，用於定義輸入（請求）參數。除非另有說明，不然這些參數應該被每個Request部分繼承。

應該包含至少一個嵌套的Response部分，以及可能包含額外的嵌套Request和Response部分。

嵌套的Request和Response部分可能被排序成組，每一個組表明一個事務示例。第一個事務示例組從第一個嵌套的Request或Response部分開始，後續組從響應部分後的第一個嵌套Request部分開始。

一個事務示例中的多個Request和Response嵌套部分應具備不一樣的標識符。

例子：

# Blog Posts [/posts{?limit}]
 ...

## Retrieve Blog Posts [GET]
Retrieves the list of **ACME Blog** posts.

+ Parameters
    + limit (optional, number) ... Maximum number of posts to retrieve

+ Response 200

        ...

## Create a Post [POST]

+ Attributes

        ...

+ Request

        ...

+ Response 201

        ...

## Delete a Post [DELETE /posts/{id}]

+ Parameters
    + id (string) ... Id of the post

+ Response 204

例子：多個事務的示例：

# Resource [/resource]
## Create Resource [POST]

+ request A

        ...

+ response 200

        ...

+ request B

        ...

+ response 200

        ...

+ response 500

        ...

+ request C

        ...

+ request D

        ...

+ response 200

        ...

上例展現了3個事務：

request A, response 200
request B, response 200 and 500
request C and D, response 200

1.3.3.8. Request section

關鍵字 Request，後跟可選的標識符：

+ Request <identifier> (<Media Type>)

例子：

+ Request Create Blog Post (application/json)

        { "message" : "Hello World." }

1.3.3.9. Response section

關鍵字 Response，後面應該使用HTTP狀態碼做爲標識符：

+ Response <HTTP status code> (<Media Type>)

例子：

+ Response 201 (application/json)

            { "message" : "created" }

1.3.3.10. URI parameters section

關鍵字 Parameters，markdown列表的形式：

+ Parameters

在父section的範圍內來討論 URI parameters.

這個section只能做爲嵌套的列表項。不能包含其餘的元素。一個列表項只能描述一個 URI parameter。

+ <parameter name>: `<example value>` (<type> | enum[<type>], required | optional) - <description>

    <additional description>

    + Default: `<default value>`

    + Members
        + `<enumeration value 1>`
        + `<enumeration value 2>`
        ...
        + `<enumeration value N>`

<parameter name> 是寫在 Resource section的URI中的參數名（好比 "id"）.
<description> 可選，markdown格式.
<additional description> 額外的可選的markdown格式的描述。
<default value> 可選，參數的默認值。
<example value> 可選，參數值的示例，好比 1234.
<type> 可選，指望的類型（好比："number", "string", "boolean"），"string" 是默認值。
Members 是可選的，列舉出可能的值。若是有Members，那麼 <type> 須要用 enum[] 包含。例如，若是提供了枚舉值，參數類型是 number, 那麼應該使用 enum[number] 而不是 number。
<enumeration value n> 列舉枚舉類型的一個元素。
required 必選，默認值。
optional 可選。

NOTE: 這個section應該只列舉出在URI模板中指定的參數，沒必要把全部的參數都列出。

示例：

# GET /posts/{id}

+ Parameters
    + id - Id of a post.

+ Parameters
    + id (number) - Id of a post.

+ Parameters
    + id: `1001` (number, required) - Id of a post.

+ Parameters
    + id: `1001` (number, optional) - Id of a post.
        + Default: `20`

+ Parameters
    + id (enum[string])

        Id of a Post

        + Members
            + `A`
            
            + `B`
            
            + `C`

1.3.3.11. Attributes Section

+ Attributes <Type Definition>

<Type Definition> 是要描述的數據結構的類型定義。若是沒有指定，將假定一個對象基本類型。細節請看MSON Type Definition

示例：

+ Attributes (object)

使用markdown語法描述一個數據結構。基於父section，數據結構被描述爲如下之一：

資源數據屬性（Resource section）
Action請求屬性（Action section）
負載消息體屬性（Payload section）

定義在這個部分的數據結構可能會引用定義在其餘數據結構部分的結構，以及由命名資源屬性描述定義的任何數據結構(見下文).

資源屬性

若是數據結構定義爲命名資源，那麼其餘數據結構可使用資源名引用它。

示例：

# Blog Post [/posts/{id}]
Resource representing **ACME Blog** posts.

+ Attributes
    + id (number)
    + message (string) - The blog post article
    + author: john@appleseed.com (string) - Author of the blog post

NOTE: 這個數據結構能夠被這樣引用：

+ Attributes (Blog Post)

Action屬性

若是定義了，Action section下的全部Request都繼承這些屬性，除非另有指定。

示例：

## Create a Post [POST]

+ Attributes
    + message (string) - The blog post article
    + author: john@appleseed.com (string) - Author of the blog post

+ Request (application/json)

+ Request (application/yaml)

+ Response 201

Payload屬性

沒必要把全部屬性都描述。若是描述了一個屬性，那麼這個屬性應該出如今Body示例中（若是有Body部分的話）。

若是定義了，Body部分可能被省略了，那麼示例應該從屬性描述中產生。

若是沒有Schema部分的話，消息體屬性的描述可能被用於描述消息體的校驗。若是有Schema的話，屬性描述應該和Schema一致。

## Retrieve a Post [GET]

+ Response 200 (application/json)

    + Attributes (object)
        + message (string) - Message to the world

    + Body

            { "message" : "Hello World." }

1.3.3.12. Headers section

+ Headers

指定父payload部分的HTTP消息頭。語法指望是下面這樣的預格式化代碼塊：

<HTTP header name>: <value>

示例：

+ Headers

        Accept-Charset: utf-8
        Connection: keep-alive
        Content-Type: multipart/form-data, boundary=AaB03x

1.3.3.13. Body section

指定payload部分的消息體。

示例：

+ Body

        {
            "message": "Hello"
        }

1.3.3.14. Data Structures section

定義在這個section的數據結構能夠被用於任何屬性section。相似地，定義在屬性section的任何數據結構也能夠被用於數據結構定義中。

示例：

# Data Structures

## Message (object)

+ text (string) - text of the message
+ author (Author) - author of the message

## Author (object)

+ name: John
+ email: john@appleseed.com

示例：在資源中複用數據結構：

# User [/user]

+ Attributes (Author)

# Data Structures

## Author (object)

+ name: John
+ email: john@appleseed.com

示例：在數據結構中複用定義的資源：

# User [/user]

+ Attributes
    + name: John
    + email: john@appleseed.com

# Data Structures

## Author (User)

1.3.3.15. Relation section

格式：

+ Relation: <link relation identifier>

這個section爲給定的Action指定鏈接關係類型，如RFC 5988指出的那樣。

NOTE: 在文檔中，每一個資源的鏈接關係標識符應該是惟一的。

示例：

# Task [/tasks/{id}]

+ Parameters
    + id

## Retrieve Task [GET]

+ Relation: task
+ Response 200

        { ... }

## Delete Task [DELETE]

+ Relation: delete
+ Response 204

1.4. 附錄

1.4.1. URI 模板

一個簡單的URI路徑段像這樣：

/path/to/resources/42

模板變量

變量名是大小寫敏感的。容許的變量名只能包含如下幾種：

ASCII字符（a-z, A-Z）
數字（0-9）
_
百分比編碼字符
.

多個變量之間用逗號分隔，逗號先後不能有空格。變量必須包含在{}中，先後也不能有空格。

操做符

括號中第一個變量前可能有一個操做符。容許的操做符以下：

# 片斷標識符操做符
+ 保留值操做符
? 表單式查詢操做符
& 表單式查詢鏈接操做符

示例：

{var}
{var1,var2,var3}
{#var}
{+var}
{?var}
{?var1,var2}
{?%24var}
{&var}

下面的字符在變量名中屬於保留字符：

: / / / ? / # / [ / ] / @ / ! / $ / & / ' / ( / ) / * / + / , / ; / =

路徑分段變量

沒有任何操做符：

/path/to/resources/{var}

若是 var := 42，那麼應該是 /path/to/resources/42.

片斷標識符變量

/path/to/resources/42{#var}

若是 var := my_id,那麼/path/to/resources/42#my_id.

包含保留字符的變量

/path/{+var}/42

若是 var := to/resources, 那麼 /path/to/resources/42.

表單式查詢操做符

/path/to/resources/{varone}{?vartwo}

若是 varone := 42 而且 vartwo = hello, 那麼 /path/to/resources/42?vartwo=hello.

/path/to/resources/{varone}?path=test{&vartwo,varthree}

若是 varone := 42, vartwo = hello, varthree = 1024, 那麼 /path/to/resources/42?path=test&vartwo=hello&varthree=1024.

1.5. 解析工具 aglio

sudo npm install aglio

可能會出現 read ECONNRESET 錯誤，根據 stack overflow 上的解答，執行下面的命令：

npm config set registry http://registry.npmjs.org/

npm 會請求 http 而不是 https 了。

相關標籤/搜索

每日一句

每一个你不满意的现在，都有一个你没有努力的曾经。