如何将文档/描述添加到 Header 参数？

Question

对于Headers部分，我需要描述每个头参数/字段/条目是什么。我该怎么做呢？

目前，我的Headers 部分如下所示：

+ Headers

        Access-Token: access_token # Server-generated Access Token to authenticate API calls from a user
        User-ID: user_id_from_google # Google-generated ID of each user
        Install-ID: randomly_generated_id # An ID to uniquely identify a device installation for a user

我使用# 暗示之后的任何内容都是该参数的comment。

Answer 1

在当前版本的 API 蓝图中还不能对标头进行内联注释。

您可以将标题的描述移动到资源或操作描述中。使用表格，您可以提供标题和描述。例如：

## GET /

### Headers

|Header|Description|
|------|-----------|
| Authorization| The authorization token |

+ Request
    + Headers

            Authorization: Bearer foo

+ Response 204

它将在 Apiary 中呈现如下：

将来，我们希望将 MSON 添加到 API 蓝图的标头中。这将允许您描述内联标题 (https://github.com/apiaryio/api-blueprint-rfcs/pull/3)。