试图描述API蓝图请求和响应使用数据结构 [英] Trying to describe the request and response using Data Structures in API Blueprint

问题描述

我试图记录与API蓝图端点，使用规范的新属性和数据结构部分。

我的请求负载是这样的：

  {
    URL：http://requestb.in/11v7i7e1
    主动：真实，
    类型：[
        {
            名：销售，
            版本：2.0
        }，
        {
            名：产品，
            版本：2.0
        }
    ]
}
 

我的响应负载看起来就像这样：

  {
  数据：{
    ID：dc85058a-a683-11e4-ef46-e9431a15be8c
    URL：http://requestb.in/11v7i7e1
    主动：真实，
    类型：[
      {
        名：产品，
        版本：2.0
      }，
      {
        名：销售，
        版本：2.0
      }
    ]
  }
}
 

我尝试以下API蓝图降价：

  FORMAT：1A＃鬻REST API 2.0＃集团网络挂接## API / 2.0 /网络挂接[/网络挂接]###列出所有网络挂接[GET]
返回由授权的应用程序创建网络挂接的列表。+响应200（应用/ JSON）
    +属性（网络挂接集合）###添加一个新的网络挂接[POST]
创建一个新的网络挂接。+属性（网络挂接基地）+请求（应用程序/ JSON）
    +属性（网络挂接基地）+响应200（应用/ JSON）
    +属性（网络挂接响应）＃数据结构##网络挂接基地（对象）
+网址：https://example.com/webhook（字符串，必需） - 在网络挂接应当提交请求的地址。
+主动：真（布尔值，必需） - 此字段可用于检查或网络挂接的编辑状态。
+类型：数组[网络挂接类型]（数组[网络挂接类型]，必需） - 网络挂接类型应触发事件网络挂接收集。##网络挂接响应基地（网络挂接基地）
+ ID：dc85058a-a683-11e4-ef46-e8b98f1a7ae4（字符串，必需） - 网络挂接`id`。##网络挂接响应（对象）
+数据：网络挂接（网络挂接响应基地，必需）##网络挂接类型（对象）
+名称：销售（字符串，必需） - 一个：产品，销售，客户，税
+版本：2.0（字符串，必需） - 有效载荷的版本交付。目前唯一支持的值为2.0。##网络挂接集合（对象）
+数据：数组[网络挂接响应基地]（数组[网络挂接响应基地]，必需） - 网络挂接对象的数组。
 

现在，它在蜂房看时，它告诉我，这是一个有效的API文档的蓝图，但它确实没怎么我JSON $请求和响应p $ pviews。
都是这样的结构，甚至有可能在API蓝图重新present并能够在蜂房很好地呈现？

解决方案

这是两个问题，一个组合：

1. 的语法不正确


2. 的bug rednering

1。 Sytnax

这个问题似乎在这里：

  ##网络挂接集（对象）
+数据：数组[网络挂接响应基地]（数组[网络挂接响应基地]，必需） - 网络挂接对象的数组。
 

看着 +数据：数组[网络挂接响应基地]（数组[网络挂接响应基地]）。 Basicaly当一个预期值，（在之后：），应提供一个值。相反 - 在这种情况下 - 你必须有一个类型数组[网络挂接响应基地] 。

让我展示一个简单的例子：

  +数据：数量（数组[数字]）
 

为不正确。

正确的版本是

  +数据：42（数组[数字]）
 

或

  +数据（数组[数字]）
    + 42
 

或

  +数据（阵列）
    + 42（数）
 

2。臭虫rednering

即使你会纠正它不会Apairy呈现的蓝图。这是我们在我们的JSON渲染发现的错误。据报道这里 https://github.com/apiaryio/drafter.js/issues/ 26 我们计划尽快将其修复。

  

这个现在已修正

修正蓝图

  FORMAT：1A＃鬻REST API 2.0＃集团网络挂接## API / 2.0 /网络挂接[/网络挂接]###列出所有网络挂接[GET]
返回由授权的应用程序创建网络挂接的列表。+响应200（应用/ JSON）
    +属性（网络挂接集合）###添加一个新的网络挂接[POST]
创建一个新的网络挂接。+属性（网络挂接基地）+请求（应用程序/ JSON）
    +属性（网络挂接基地）+响应200（应用/ JSON）
    +属性（网络挂接响应）＃数据结构##网络挂接基地（对象）
+网址：https://example.com/webhook（字符串，必需） - 在网络挂接应当提交请求的地址。
+主动：真（布尔值，必需） - 此字段可用于检查或网络挂接的编辑状态。
+类型（数组[网络挂接类型]，必需） - 网络挂接类型应触发事件网络挂接收集。##网络挂接响应基地（网络挂接基地）
+ ID：dc85058a-a683-11e4-ef46-e8b98f1a7ae4（字符串，必需） - 网络挂接`id`。##网络挂接响应（对象）
+数据（网络挂接响应基地，必需）##网络挂接类型（对象）
+名称：销售（字符串，必需） - 一个：产品，销售，客户，税
+版本：2.0（字符串，必需） - 有效载荷的版本交付。目前唯一支持的值为2.0。##网络挂接集合（对象）
+的数据（ARRAY [网络挂接响应基地]，必需） - 网络挂接对象的数组。
 

---

希望这回答了你的问题。请让我知道是否需要进一步澄清。

I'm trying to document an endpoint with API Blueprint, using the new Attributes and DataStructures sections of the spec.

My request payload looks like this:

{
    "url": "http://requestb.in/11v7i7e1",
    "active": true,
    "types": [
        {
            "name": "sales",
            "version": "2.0"
        },
        {
            "name": "products",
            "version": "2.0"
        }
    ]
}

My response payload looks something like that:

{
  "data": {
    "id": "dc85058a-a683-11e4-ef46-e9431a15be8c",
    "url": "http://requestb.in/11v7i7e1",
    "active": true,
    "types": [
      {
        "name": "products",
        "version": "2.0"
      },
      {
        "name": "sales",
        "version": "2.0"
      }
    ]
  }
}

I tried the following API Blueprint markdown:

FORMAT: 1A

# Vend REST API 2.0

# Group Webhooks

## api/2.0/webhooks [/webhooks]

### List all Webhooks [GET]
Returns a list of Webhooks created by the authorised application.

+ Response 200 (application/json)
    + Attributes (Webhook Collection)

### Add a new Webhook [POST]
Creates a new Webhook.

+ Attributes (Webhook Base)

+ Request (application/json)
    + Attributes (Webhook Base)

+ Response 200 (application/json)
    + Attributes (Webhook Response)

# Data Structures

## Webhook Base (object)
+ url: https://example.com/webhook (string, required) - The address where webhooks requests should be submitted.
+ active: true (boolean, required) - This field can be used to inspect or edit state of the webhook.
+ types: array[Webhook Type] (array[Webhook Type], required) - Collection of Webhook types which should trigger Webhook event.

## Webhook Response Base (Webhook Base)
+ id: dc85058a-a683-11e4-ef46-e8b98f1a7ae4 (string, required) - Webhook `id`.

## Webhook Response (object)
+ data: webhook (Webhook Response Base, required)

## Webhook Type (object)
+ name: sales (string, required) - One of: products, sales, customers, taxes
+ version: 2.0 (string, required) - Version of the payload to be delivered. Currently the only supported value is "2.0".

## Webhook Collection (object)
+ data: array[Webhook Response Base] (array[Webhook Response Base], required) - An array of Webhook objects.

Now, when looking at it in Apiary, it tells me that this is a valid API Blueprint document, but it doesn't how me JSON previews for the request and response. Are structures like this even possible to represent in API Blueprint and able to render nicely in Apiary?

解决方案

This is a combination of two problems:

1. incorrect syntax
2. bug in rednering

1. Sytnax

The problem seems to be here:

## Webhook Collection (object)
+ data: array[Webhook Response Base] (array[Webhook Response Base], required) - An array of Webhook objects.

Looking at + data: array[Webhook Response Base] (array[Webhook Response Base]). Basicaly when a value is expected (after the :) a value should be provided. Instead – in this case – you have there a type array[Webhook Response Base].

Let me demonstrate on a simpler example:

+ data: number (array[number])

is incorrect.

Correct version would be

+ data: 42 (array[number])

or

+ data (array[number])
    + 42

or

+ data (array)
    + 42 (number)

2. Bug in rednering

Even if you would correct the blueprint it won't be rendered in Apairy. This is a bug we have discovered in our JSON renderer. It has been reported here https://github.com/apiaryio/drafter.js/issues/26 we plan to fix it ASAP.

This has been fixed now

Corrected blueprint

FORMAT: 1A

# Vend REST API 2.0

# Group Webhooks

## api/2.0/webhooks [/webhooks]

### List all Webhooks [GET]
Returns a list of Webhooks created by the authorised application.

+ Response 200 (application/json)
    + Attributes (Webhook Collection)

### Add a new Webhook [POST]
Creates a new Webhook.

+ Attributes (Webhook Base)

+ Request (application/json)
    + Attributes (Webhook Base)

+ Response 200 (application/json)
    + Attributes (Webhook Response)

# Data Structures

## Webhook Base (object)
+ url: https://example.com/webhook (string, required) - The address where webhooks requests should be submitted.
+ active: true (boolean, required) - This field can be used to inspect or edit state of the webhook.
+ types (array[Webhook Type], required) - Collection of Webhook types which should trigger Webhook event.

## Webhook Response Base (Webhook Base)
+ id: dc85058a-a683-11e4-ef46-e8b98f1a7ae4 (string, required) - Webhook `id`.

## Webhook Response (object)
+ data (Webhook Response Base, required)

## Webhook Type (object)
+ name: sales (string, required) - One of: products, sales, customers, taxes
+ version: 2.0 (string, required) - Version of the payload to be delivered. Currently the only supported value is "2.0".

## Webhook Collection (object)
+ data (array[Webhook Response Base], required) - An array of Webhook objects.

---

Hope this answers your question. Please let me know if a further clarification is needed.

这篇关于试图描述API蓝图请求和响应使用数据结构的文章就介绍到这了，希望我们推荐的答案对大家有所帮助，也希望大家多多支持IT屋！