mercredi 22 avril 2015

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

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://ift.tt/1HnbCEX",
    "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://ift.tt/1HnbCEX",
    "active": true,
    "types": [
      {
        "name": "products",
        "version": "2.0"
      },
      {
        "name": "sales",
        "version": "2.0"
      }
    ]
  }
}

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: http://ift.tt/1DPB4io (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, 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?

Aucun commentaire:

Enregistrer un commentaire