编写Api-blueprint文档

一、新建Api-blueprint文档

1.1 下载文档编辑工具Atom

打开官网下载 Atom

1.2 安装Atom插件

安装Api-blueprint文档预览插件，可以实时检查

1. language-api-blueprint：语法高亮

2. api-blueprint-preview：实时预览

安装方法：依次点击 Atom -> Preferences -> Install 在搜索框中输入 language-api-blueprint 选择 Packages 进行搜索，把红色框框内的两个插件分别点击 Install，如下图所示就算安装完成。

插件下载安装完成后，点击 language-api-blueprint 的 Settings，然后勾选：

1. Show Indent Guide：显示缩进，因为 API BluePrint 对缩进要求比较高，这个开着比较好，方便排错；

2. Show Invisibles：显示空格，Tab键，以及换行符；

1.3 新建文档

打开 Atom，Command + N 新建一个标签页，然后保存为api.apib，文件扩展名apib是 API BluePrint 的缩写。语法高亮，实时预览效果如下：

二、编写 API 文档

1. 官方文档

2. 官方例子

我们主要会用到这几个部分：

• Metadata section 元数据

• API name & overview section API 名称和说明

• Resource group section 资源分组

• Schema section

• Action section 动作（POST、GET）

• Request section 请求

• Response section 响应

• URI parameters section 请求URL参数

• Headers section 请求头

• Body section 请求数据

2.1 Metadata 元数据

Example

FORMAT: 1A

你需要使用一个元数据(metadata)，来明确指定API Blueprint的版本。比如在上述文件中我们使用的版本号是1A。

2.2 API name & overview section

API 名字以及简单的描述

Example

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

2.3 Resource group section

可以把接口按功能模块进行分类，Group 后面跟类名

Example

# Group 员工管理

2.4 Action section

在这儿我们定义POST/GET请求

书写格式：

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

Example

## 商户-门店列表查询  [POST /store/app/search{?storeName,enable,pageNO,pageCount}]

URI template书写格式：以/store/app/search{?storeName,enable,pageNO,pageCount}为例。

• /store/app/search：URL链接

• {?storeName,enable,pageNO,pageCount}：大括号内是参数，以？开头，参数之间,进行分割

2.5 Response section 响应

书写格式：

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

Example

+ Response 201 (application/json)

            { "message" : "created" }

2.6 URI parameters section 参数

Example

+ Parameters

    + storeName (string,required) - 门店名字,字符串
    + enable (numberl ,optional) - 状态,整型  0:启用,1:注销 -1默认查全部
    + pageNO (numberl,required) - 页码, 整型 第一页默认 1 必填
    + pageCount (numberl,required) - 每页显示条数, 整型  必填 

• required/optional：如果不填，默认required

2.7 Headers section

书写格式：

<HTTP header name>: <value>

Example

+ Headers

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

2.8 Body section

Body是文档比较关键的一环，里面的内容既是需要模拟的数据，也就是mock server的数据源。

Example1

+ Body

        {
            "message": "Hello"
        }

Example2

+ Body

        {
                "success": true,
                "err_code": "888888",
                "err_msg": "错误说明",
                "data":{
                    "id": 39,
                    "storeId":43,
                    "realname": "屠神", 
                    "mobilePhone": "13554477744",
                    "storeName": "杭州店",
                    "type":0,
                    "sex": 1,
                    "enable": 1,
                    "username": "chenlong01",
                    "portrait":"头像"
                }
            }

2.9 Schema section

作用：返回数据的备注说明

注：下面的Example与2.8中的Example2对应着看

Example

+ Schema

            {
                "data": {
                        "id": "员工id,整型",
                         "storeId": "门店ID，字符串",
                        "storeName": "门店名字",
                        "realname": "员工姓名，字符串",
                        "mobilePhone": "手机号，字符串",
                        "sex": "性别，0：男  1：女",
                        "enable": "启用状态，0：启用；1：禁用",
                        "username": "账号，字符串",
                        "portrait": "头像链接，字符串"
                        }
            }

三、Demo

创建了一个项目：ApiBlueprintDemo-master

Project中包含：

• API Bueprint 文档

• API Bueprint 文档生成的 HTML：可以本地打开预览下效果，支持在线查询

参考文档

• 使用 API BluePrint 编写 RESTful 接口文档