Api-blueprint: 需要在相同资源上执行相同 HTTP 动词的多个操作（但请求内容类型不同）

更新：我发现我可以通过只说明一个响应来做到这一点：

FORMAT: 1A
# multiple posts?
## Try to make two posts [/v1/whatever]
### POST
+ Request JSON (application/json)
        { nil: nil }
+ Request DNS (text/dns)
        whatever
+ Response 204

但是，这在嵌入模式下无法正确显示（仅显示一种请求类型）。 编辑器中的预览和文档视图很好。

@jrep

这在当前的 Apiary 嵌入（设计）中似乎乏善可陈。 我已将此问题通知@apiaryio团队。

@jrep是这里的请求（在嵌入限制旁边）支持多个响应？

如果是这样，以下应该已经有效：

FORMAT: 1A

## Try to make two posts [/v1/whatever]

### POST

+ Request JSON (application/json)

        JSON

+ Response 200 (application/json)

        JSON       

+ Request DNS (text/dns)

        whatever

+ Response 200 (text/dns)

        whatever

您的示例显示了多个请求，但只有一个响应。 这就像我的例子。 是的，这在语法上是有效的，但它无法表达我们需要表达的内容。

是的：这里需要为每个请求显示不同的“响应 200”。 响应内容类型与请求内容类型匹配（因此两个请求内容类型意味着两个响应内容类型），但两个响应中的信息并不完全等效。

使用 Legacy 格式，我们定义了一个请求及其响应，然后是下一个请求/响应对。 这是新格式中的语法错误，似乎没有任何有效的说法。

更新：哎呀，我看的不够仔细：您的示例至少在两个方面与我的不同：两个响应和命名请求的使用。 现在正在尝试。

@jrep

我不确定你是什么意思。 你能在这里提交一个遗留蓝图的片段吗？

Github 票证不允许我附加文本。 您可以从https://dev-staging.akamai.com/api/luna/config-dns/blueprint.apib获取旧版蓝图

知道了

POST /v1/zones/{zone}
> Content-Type: application/json
... some data ...
< 204
< Location: /v1/zones/example.com

POST /v1/zones/{zone}
> Content-Type: text/dns
... some other data ...
< 204
< Location: /v1/zones/example.com

我认为基本上可以将其表达为：

## Zone [/v1/zones/{zone}]

### Create [POST]

+ Request Create with JSON (application/json)

        { ... json data ... }

+ Request Create with DNS (text/dns)

        ... dns data ...

+ Response 204
    + Headers

            Location: /v1/zones/example.com

http://docs.multirequest.apiary.io

这是一个经典的内容协商示例。 从许多不同的表示中创建一个资源，而响应没有正文，只是状态良好（可能还有一个链接）。

与之对应的内容协商将是：

### Retrieve [GET]

+ Request Rerieve JSON representation
    + Headers

            Accept: application/json

+ Response 200 (application/json)

        { ... json data ... }

+ Request Rerieve DNS representation
    + Headers

            Accept: text/dns

+ Response 200 (text/dns)

        ... dns data ...

我认为对内容类型不同但具有相同含义（创建资源）的多个请求的无正文响应是好的设计。 但是，我确实想通过实施https://github.com/apiaryio/snowcrash/issues/53来解除此限制（当有多个具有相同状态和内容类型的响应时发出警告）

@jrep此问题已在https://github.com/apiaryio/snowcrash/issues/53 (Snow Crash v0.10.0) 中解决，因此我将其关闭。 如果需要，请评论并重新打开。

尽管一个端点可以有多个事务示例，如apiaryio/snowcrash#53 中所见，这些在 Apiary 中渲染得不是很清楚。

看下面的例子...

您有/oauth2/authorize ，根据规范，它将处理各种不同的场景（例如从刷新获取访问令牌，或从密码生成令牌等）。 将这些合并为 API 文档上的单个操作让读者很难理解，相反，用户更容易在侧边菜单中拥有多个端点，例如“刷新访问令牌”和“验证用户”。 但是这是不可能的，因为您不能两次指定相同的方法/URL 组合。

这是 API 规范强制其开发人员使用某种方法的一个主要示例，并且在上述情况下，不适合常见的设计模式。

我看到不正确的语法突出显示 - 查看Body的颜色：