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

Question

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

目前，我的 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 蓝图中尚无法注释 headers 内联。

您可以将 headers 的描述移动到资源或操作描述中。使用 table，您可以提供 headers 和说明。例如：

## GET /

### Headers

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

+ Request
    + Headers

            Authorization: Bearer foo

+ Response 204

将在 Apiary 中呈现如下：

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

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

How do I add documentation / description to a Header parameter?

apiary.io

apiblueprint

apiary