尝试使用数据结构在API Blueprint中描述请求和响应。

Question

尝试使用数据结构在API Blueprint中描述请求和响应。

12

我正在尝试使用API Blueprint文档化一个端点，使用规范的新属性和数据结构部分。

我的请求负载看起来像这样:

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

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

{
  "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蓝图的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中漂亮地呈现？

- Piotr Zurek

1

嘿，我认为这是由于您的描述中存在一些错误以及apiary中的一个小错误的组合。给我一个小时左右，我应该能够给您更多信息。 - Pavan Kumar Sunkara

太棒了！很高兴听到这不是完全不可能的。:-)期待您的回答。 - Piotr Zurek

1个回答

网页内容由stack overflow 提供, 点击上面的

可以查看英文原文，
原文链接

- Zdenek · Accepted Answer

这是两个问题的组合：

语法不正确
渲染时出现错误

1. 语法

问题似乎在这里：

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

查看+ data：array [Webhook Response Base]（array [Webhook Response Base]）。基本上，当需要一个值（在：之后）时应该提供一个值。然而，在这种情况下，你提供的是一个类型为array [Webhook Response Base]的值。

让我通过一个更简单的例子来说明：

+ 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 ，我们计划尽快修复它。

这个问题现在已经得到解决

更正后的蓝图

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.

希望这回答了你的问题。如果需要进一步澄清，请告诉我。