12

仕様の新しい Attributes セクションと DataStructures セクションを使用して、API ブループリントでエンドポイントを文書化しようとしています。

私のリクエストペイロードは次のようになります。

{
    "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 ブループリント マークダウンを試しました。

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 ブループリントで表現でき、Apiary で適切にレンダリングできますか?

4

1 に答える 1

21

これは、次の 2 つの問題の組み合わせです。

  1. 間違った構文
  2. レンダリングのバグ

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])ます。基本的に、値が期待される場合 ( の後:)、値を提供する必要があります。代わりに – この場合 – type があります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.

これがあなたの質問に答えることを願っています。さらに説明が必要な場合はお知らせください。

于 2015-04-23T19:55:46.837 に答える