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

问题描述

我正在尝试使用规范的新属性和数据结构部分为 API 蓝图记录端点.

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

我尝试了以下 API 蓝图降价:

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.

现在，当在 Apiary 中查看它时，它告诉我这是一个有效的 API 蓝图文档，但它不是我如何预览请求和响应的 JSON.这样的结构甚至可以在 API Blueprint 中表示并能够在 Apiary 中很好地呈现吗?

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?

推荐答案

这是两个问题的组合:

1. 不正确的语法
2. 渲染错误

1.语法

问题似乎在这里:

1. Syntax

The problem seems to be here:

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

看+数据:array[Webhook Response Base] (array[Webhook Response Base]).基本上，当需要一个值时(在 : 之后)应该提供一个值.相反 - 在这种情况下 - 你有一个类型 array[Webhook Response Base].

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])

不正确.

正确的版本是

+ data: 42 (array[number])

或

+ data (array[number])
    + 42

或

+ data (array)
    + 42 (number)

2.渲染错误

即使您修正了蓝图，它也不会在 Apairy 中呈现.这是我们在 JSON 渲染器中发现的一个错误.它已在此处报告 https://github.com/apiaryio/drafter.js/issues/26 我们计划尽快修复它.

2. Bug in rendering

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.

现在已经修复了

更正的蓝图

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