问题标签 [apiblueprint]

我编写了一个小型 Web 服务，该服务被设计为“可卷曲”，因此它依赖于请求中的application/x-www-form-urlencoded参数，例如：POST

我想使用Apiary记录此服务，但我一直无法找到为这些参数提供结构化文档的方法。我可以提供这样的示例请求...

...但这不允许我提供有关各个参数的文档（并且不适合在养蜂场控制台中进行测试，因为它无法为各种参数提供输入字段）。

我已经通读了几次api 蓝图规范，但一直找不到好的解决方案。有没有办法为这些参数提供结构化文档？

我对 Web API 描述语言的世界还很陌生，并且刚刚开始为我们的 JAX-RS 应用程序研究 Swagger、API 蓝图和 RAML。它们看起来都很棒，但我有一个问题。

我的理解是自上而下的方法，你首先设计你的 API，生成一个漂亮的 HTML 文档，可能还有一个模拟，然后开始编码。

但是，如果在实施过程中由于某些原因最终不得不更改 API 的签名，例如更改响应主体模型，该怎么办？我的意思是在这种情况下，您的 API 规范需要更改，并且您必须手动编辑您的 API 规范以使其与您的代码保持同步，因为似乎没有成熟的库可以从源代码生成 API 规范。（我已经为 Swagger 和 RAML 测试了此类库，但没有测试 APIB，因为我找不到 JAX-RS 源 APIB 转换库。）在上述情况下，您如何处理它？

您是手动编辑 API Spec 还是使用某些库自动进行编辑？如果是后者，你能告诉我图书馆的名字吗？

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

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

创建 Blueprint API 文档时如何在 URL 中格式化基于哈希的参数？

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

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

在过去一个月左右的时间里，我们的 Apiary API 发生了故障。这是我们的一个主要问题，因为我们的构建不断失败。

这似乎与我们的 URI 定义中的参数有关，需要 URL 编码。

例如：

nobody%40example.com 不再工作（404 错误），但 nobodyexample.com 是。

我想知道最近在养蜂场方面是否发生了任何可能导致这种情况的变化？

这是整个蓝图：

阅读API Blueprint specification，似乎设置为允许指定“数据结构”，例如：

• 地址
  • 街道：100 Main Str. （字符串） - 街道地址
  • 邮编：77777-7777（字符串）-邮政编码

...

• 顾客：
  • 句柄：mrchirpy（字符串）
  • 地址：（地址）

然后在模型中，引用数据结构：

• 模型

  [顾客][]

似乎一切都设置为通过引用数据结构，它应该生成与端点一致的文档和示例。

但是，我似乎无法让它工作，也找不到使用“完全规范化数据抽象”的示例。我想定义一次我的数据结构，然后到处引用。看起来这可能是工具的问题，特别是我使用aglio作为渲染代理。

似乎所有这些都是折叠类型的东西，所以我很困惑，想知道我是否遗漏了一些东西，或者对这里可能发生的事情做出了错误的假设。

我正在尝试使用规范的新属性和数据结构部分使用 API 蓝图记录端点。

我的请求有效负载如下所示：

我的响应负载看起来像这样：

我尝试了以下 API 蓝图降价：

现在，当在 Apiary 中查看它时，它告诉我这是一个有效的 API 蓝图文档，但它不是 JSON 预览请求和响应的方式。像这样的结构甚至可以在 API 蓝图中表示并能够在 Apiary 中很好地呈现吗？

我在 Apiary 蓝图示例中看到了以下操作部分。当用户传递错误的参数时，我想以 HTTP 状态 404 进行响应。例如，当用户通过 /questions/xyz 而不是 /questions/1 时。如您所见，我们定义 /questions 之后的参数必须是数字，但是当我传递 xyz 而不是数字时，它会以相同的对象回答。

请给我写完整的代码。提前致谢。

我目前有这样的 API 蓝图，但我无法实现正确的渲染。

我的问题是：

• 主要是我想有请求和响应有效负载的表。我想实现布局：“响应”-> 带有作为响应有效负载的 json 对象字段的表。如果我输入“+ Attributes”（请参阅​​我的蓝图），我设法让它显示出来，但是当你有一个 json 对象作为有效负载时，我不确定这是描述这种情况的正确方法。也许应该使用其他关键字？

• 当使用描述为“+ SampleProperties(SamplePropertiesDTO)”的字段渲染表格时，它在渲染页面中显示为表格中的一行，作为对象类型的 SampleProperties，并且在渲染页面上找不到 SamplePropertiesDTO 的内容。然而，我将它内联或作为文档的单独部分存在，例如所有数据结构所在的位置。

• 如果可能的话，我想单独显式地显示数据结构对象的表。目前数据限制部分不会以任何方式显示在屏幕上。我怎么能那样做？

In my WebAPI being desinged, I have urls such as

and I need to specify another method with POST and same base URL, that does things similarly to original, but accepts different payload and returns different payload. At the moment I have

"modification" but I am not sure it is a good API practice. What would be the best way to design a modifier for method without necessity to change the resource URL? What would be the best practice - use another HTTP verb, add ?optionalparameter to URL, or something else?

我有许多需要发送 X-Auth-Token 标头的服务，类似于以下内容：

我希望能够按照 API 蓝图标准在我的 API 文档中指定这一点。但是，根据我从 API Blueprint headers section definition中可以看出，您只能指定文字值（例如Accept-Charset: utf-8），而不是标头应该是什么样子的模式（例如，类似于X-Auth-Token (string)）。

我的印象是 Traits 可能有助于解决这个问题，但目前这有点超出我的想象。谁能告诉我如何指定对给定操作（或一组操作）的所有请求都需要 X-Auth-Token 标头？