Versuche, die Anforderung und Antwort mithilfe von Datenstrukturen in API Blueprint zu beschreiben

Question

Apr 23, 2015, 01:31 AM

Versuche, die Anforderung und Antwort mithilfe von Datenstrukturen in API Blueprint zu beschreiben

Ich versuche, einen Endpunkt mit API Blueprint zu dokumentieren, indem ich die neuen Abschnitte "Attribute" und "DataStructures" der Spezifikation verwende.

Meine Anforderungsnutzlast sieht folgendermaßen aus:

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

Meine Antwortnutzlast sieht ungefähr so aus:

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

Ich habe das folgende API-Blueprint-Markdown ausprobiert:

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, wenn ich es mir im Bienenhaus anschaue, sehe ich, dass es sich um ein gültiges API-Blueprint-Dokument handelt, aber nicht, wie ich eine JSON-Vorschau für die Anforderung und die Antwort sehe. Sind solche Strukturen überhaupt in API Blueprint darstellbar und in Apiary gut darstellbar?

Zu kommentieren