rest - Api Blueprint 可以理解的二维键值格式是什么？

Question

我正在使用 Api Blueprint 为 RESTful 搜索 API 开发 API 文档。我希望能够将过滤器传递给 API，以便我可以进行组装:

filter[filtername1]=filtervalue1
filter[filtername2]=filtervalue2

根据这个问题，我使用百分比编码的方括号，但与这个问题不同的是，我们不可能描述每个可能的键名称:

How to format hash-based parameters in the URL when creating Blueprint API doc?

我希望键名是可变的，因为它可以是源数据中的任何字段。这有效吗？

## Key-Value-Test [/api/v1/keyvaluetest?term={term}&filter%5B{field_name}%5D={field_value}]

+ term
+ filter_field
+ filter_value

像这样的二维数组有推荐的格式吗？这似乎在 Dredd 中不起作用，因为 + filter_field 并不真正匹配 filter[filter_field]

Answer 1

恐怕 API Blueprint 和 Apiary 还不允许此类动态 URL 定义。

API Blueprint 和 Apiary 仅允许 RFC 6570 中定义的 URI 模板

根据该 RFC，以下 URI 模板无效

GET /resource?year={year}&month={month}

您可以更改 URL 以定义如下内容:

## Key-Value-Test [/api/v1/keyvaluetest{?term,field_name,field_value}]

+ Parameters
    + term: a
    + field_name: b
    + field_value: c

此方法有两个注意事项:

• 您只能为参数指定一个字段名称和字段值。如果需要更多字段参数，则必须扩展 URL。
• 您必须更改 API 网址，但我认为您不会想要这样做。

请通过 http://support.apiary.io 发起功能请求如果你有的话。