尝试使用 API 蓝图中的数据结构来描述请求和响应

Posted 2023-03-30

【中文标题】尝试使用 API 蓝图中的数据结构来描述请求和响应

【英文标题】：Trying to describe the request and response using Data Structures in API Blueprint

【发布时间】：2015-04-22 23:31:34

【问题描述】：

我正在尝试使用规范的新属性和数据结构部分使用 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 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: 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 中很好地呈现吗？

【问题讨论】：

嘿，我认为这是由于您的描述中的错误和养蜂场中的一个小错误的组合。给我一个小时左右，我应该给你更多的信息。

太棒了！我很高兴听到这并非完全不可能。 :-) 期待您的回答。

【参考方案1】：

这是两个问题的结合：

语法错误 渲染中的错误

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])。基本上，当需要一个值时（在: 之后），应该提供一个值。相反——在这种情况下——你有一个类型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.

---

希望这能回答您的问题。如果需要进一步澄清，请告诉我。

【讨论】：

太棒了。当我拼命尝试渲染它时，我实际上已经引入了使用array[Webhook Response Base] 的错误。很高兴看到你们正在努力修复这个错误。我会在 GtiHub 上关注它，以确保在它修复后再次尝试。

@PiotrZurek 请注意，我们根据您的最新评论编辑了蓝图。

哇哦！我可以看到它现在已在 Apiary 中修复。谢谢大家。

您好，在我看来，这个答案正好符合我的需要，请您看一下好吗？ - ***.com/questions/31752483/…