Tentando descrever a solicitação e resposta usando estruturas de dados no API Blueprint
Estou tentando documentar um ponto de extremidade com o API Blueprint, usando as novas seções Atributos e DataStructures da especificação.
Minha carga útil de solicitação é assim:
{
"url": "http://requestb.in/11v7i7e1",
"active": true,
"types": [
{
"name": "sales",
"version": "2.0"
},
{
"name": "products",
"version": "2.0"
}
]
}
Minha carga útil de resposta é mais ou menos assim:
{
"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"
}
]
}
}
Tentei a seguinte remarcação de API 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] (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.
Agora, ao analisá-lo no Apiary, ele me diz que este é um documento válido do API Blueprint, mas não mostra como o JSON visualiza a solicitação e a resposta. Estruturas como essa são possíveis de representar no API Blueprint e capazes de renderizar bem no Apiary?