使用API Blueprint语法来编写API文档

toddmark 发布于2019-07-31 10:31 / 730人阅读

摘要：资源描述我们可以用的语法在名称的后面加上包含名称的说明。是指当服务器收到一个请求时候的响应。在中应该有一个状态码和数据。在这里我们定义最常见的状态码，表示请求成功。下文将介绍生成高大上的文档

1、资源Resource

</>复制代码 
# Gist Fox API Root [/]
在Blueprint里，所有的数据信息都是资源(resource)，比如用户、视频、文章。
resource的定义以#开始，中间是resource的名称，最后是用中括号包围的路径(URI)，需要注意的是URI是放在[]中的。URI是相对路径，在这里它就是个/。

2、资源描述Resource Description

</>复制代码 
# Gist Fox API Root [/]
Gist Fox API entry point.
This resource does not have any attributes. Instead it offers the initial API
我们可以用Markdown的语法在resource名称的后面加上包含API名称的说明。
在这里Gist Fox API是API名称，entry point是说明。

3、行为Action

</>复制代码 
## Retrieve Entry Point [GET]
行为action是一个HTTP请求的属性之一，在发送请求的时候会随数据一起发送到服务器。
我们在这里定义了一个action叫做Retrieve Entry Point (索引入口)，它是一个GET类型的请求。我们可以在后面加上一些描述，
但是因为这个action的名字(Retrieve Entry Point)已经把这个行为解释的很清楚了，所以我们就跳过了这一步。

4、在Blueprint有以下四种action：

</>复制代码 
- GET ： 获取数据
- POST ： 添加数据
- PUT ： 更新数据
- DELETE ： 删除数据

5、回应Response

</>复制代码 
+ Response 200
在API Blueprint中一个action应该至少包括一个回应(response)。response是指当服务器收到一个请求(request)时候的响应。
在response中应该有一个状态码status code和数据payload。
在这里我们定义最常见的状态码：200，表示请求成功。

6、响应负载Response Payload

</>复制代码 
+ Response 200 (application/hal+json)
+ Headers
Link: ;rel="self",;rel="gists"
+ Body
{
    "_links": {
        "self": { "href": "/" },
        "gists": { "href": "/gists?{since}", "templated": true }
    }
}
一个响应(response)经常包含一些负载(payload)。一个负载(payload)通常包含负载体(body)和负载头(header)两个部分。
在这个例子中，我们采用application/hal+json类型作为返回数据的类型。

7、URI模板URI Template

</>复制代码 
## Gist [/gists/{id}]
在URI中的变量需要遵守URI的模板格式，在这个例子中，Gist的编号(id)在URI中就是{id}。

8、URI参数URI Parameters

</>复制代码 
+ Parameters
+ id (string) ... ID of the Gist in the form of a hash.
这个id变量是这个resource中的一个参数(parameter)，我们定义它的类型为string，并且在后面加上一些解释。

9、资源模型Resource Model

</>复制代码 
+ Model (application/hal+json)
HAL+JSON representation of Gist Resource. In addition to representing its state in the JSON form it offers affordances in the form of the HTTP Link header and HAL links.
+ Headers
Link: ;rel="self", ;rel="star"
+ Body
{
    "_links": {
        "self": { "href": "/gists/42" },
        "star": { "href": "/gists/42/star" },
    },
    "id": "42",
    "created_at": "2014-04-14T02:15:15Z",
    "description": "Description of Gist",
    "content": "String contents"
}
资源模型Resource Model是前面定义的资源的一个样例，它可以在任何一个request或者response需要的位置引用，一个资源模型有着和前面所说的payload一模一样的结构。
在前面的例子中，还包含了一个额外的描述，也就是在+ Model和+ Headers中间的那部分内容。

ps:下文将介绍aglio生成高大上的api文档

GPU云服务器云服务器 api的方式来管理云服务器 api文档 api接口编写工具生成API文档

文章版权归作者所有，未经允许请勿转载,若此文章存在违规行为，您可以联系管理员删除。

转载请注明本文地址：https://www.ucloud.cn/yun/43956.html

使用API Blueprint语法来编写API文档

摘要：资源描述我们可以用的语法在名称的后面加上包含名称的说明。是指当服务器收到一个请求时候的响应。在中应该有一个状态码和数据。在这里我们定义最常见的状态码，表示请求成功。下文将介绍生成高大上的文档 1、资源Resource # Gist Fox API Root [/] 在Blueprint里，所有的数据信息都是资源(resource)，比如用户、视频、文章。 resource的定义以#开...

468122151 2019-08-02 15:12 评论0 收藏0
使用API Blueprint语法来编写API文档

摘要：资源描述我们可以用的语法在名称的后面加上包含名称的说明。是指当服务器收到一个请求时候的响应。在中应该有一个状态码和数据。在这里我们定义最常见的状态码，表示请求成功。下文将介绍生成高大上的文档 1、资源Resource # Gist Fox API Root [/] 在Blueprint里，所有的数据信息都是资源(resource)，比如用户、视频、文章。 resource的定义以#开...

Zhuxy 2019-06-28 10:35 评论0 收藏0
试探API Blueprint接口文档生成和接口模拟

前言今天发现了一个很niubility的东西__API Blueprint__,先给出官网https://apiblueprint.org/。下面是官网给出的介绍： API Blueprint. A powerful high-level API description language for web APIs. 这个可以干什么呢？按照API Blueprint的语法(类似markdown)，...

mist14 2019-06-27 15:41 评论0 收藏0
使用Api-blueprint文档创建mock server

摘要：是一套描述标准，和一样，属于一种标记语言，可以把标记文稿转换成漂亮的接口文档。还可以创建，进行本地调试。一语法只要用写过东西基本很快就能掌握语法。参考文档使用编写文档用生成优雅的文档指导手册用生成优雅的文档前后端配合开发的时候，常常会有这样一种需求：你接口定义好了吗？能不能先帮我起一个 Mock Server 先跑起来？那么，如何才能避免前后端开发在时间差上的无谓等待呢？api-bl...

ningwang 2019-07-24 10:34 评论0 收藏0