试图描述API蓝图请求和响应使用数据结构

问题描述

我试图记录与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渲染发现的错误。据报道这里我们计划尽快将其修复。

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蓝图请求和响应使用数据结构的文章就介绍到这了，希望我们推荐的答案对大家有所帮助，也希望大家多多支持！