使用 API 蓝图记录查询参数

Posted 2023-03-30

【中文标题】使用 API 蓝图记录查询参数

【英文标题】：Documenting query parameters with API Blueprint

【发布时间】：2014-04-03 18:12:03

【问题描述】：

我正在尝试在 API 蓝图中记录一个查询参数，但我不完全确定我是否正确地完成了它。资源如下所示：

DELETE http://baasar.apiary-mock.com/user/appId/userId

该请求将停用用户，而以下将删除用户对象：

DELETE http://baasar.apiary-mock.com/user/appId/userId?force=true

这是我为此准备的蓝图降价：

## User [/user/appId/userId]
Handle user objects

+ Parameters
    + appId (required, number, `1`) ... Application ID (`appId`)
    + userId (required, number, `1`) ... Numeric `userId` of the User object to manage

### Remove an User [DELETE]
+ Parameters
    + force (optional, boolean, `false`) ... Set to `true` to remove instead of deactivate

+ Response 204

但是，当使用 Apiary 渲染它时，我只在参数列表中看到 force，但它现在显示在示例 URL 中。这只是我对 GUI 的误解还是应该以其他方式记录查询参数？

【参考方案1】：

您的蓝图非常好，问题是当前的 Apiary 文档没有正确处理 URI 参数。

你能试试new documentation吗？它应该正确处理 URI 参数。

编辑

正确的 URI 模板应该是：

http://baasar.apiary-mock.com/user/appId/userId?force

【讨论】：

非常感谢您的回答。我应该说我已经使用了新文档。令我困惑的是，“资源参数”和“动作参数”之间没有分离。所以我认为在上面的例子中并不清楚force放在哪里。

我已将资源定义更改为类似于 ## User [/user/appId/userId?force=bool]（如果 force 不存在，我会在 Apiary 语法中出现错误）。这对于 DELETE 动词来说看起来非常好，但它让我在同一资源中的 GET 动词看起来很奇怪，因为它不支持 force 参数。

您可以在此处使用“列出所有注释”和“创建注释”查看所需的行为：docs.queryparameters.apiary.io/?3ColumnDocumentation=1 只是没有文档支持新的 URI 模板行为，因此没有人知道如何使用它。 :-/

公平点@james-h；我会将其添加到规范中github.com/apiaryio/api-blueprint/issues/79

@Baggz 离题，但那是什么主题？

【参考方案2】：

我的curl请求：

curl -k -u username:password https://api.techie8.io/api/1.0/bits?bit_type=1

养蜂场蓝图：

## Bits Collection [/bits?bit_type=bit_type]

### List Latest bits [GET]

List all bits recently inserted into database.

+ Parameters
    + bit_type (number, optional, `1`) ... Type of bit to retrieve: 1: Bits, 2: Newsletter