Trying to describe the request and response using Data Structures in API Blueprint

半世苍凉 提交于 2019-11-30 06:56:15
Zdenek

This is a combination of two problems:

  1. incorrect syntax
  2. bug in rendering

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.

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 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.

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.

易学教程内所有资源均来自网络或用户发布的内容,如有违反法律规定的内容欢迎反馈
该文章没有解决你所遇到的问题?点击提问,说说你的问题,让更多的人一起探讨吧!