问题标签 [apiblueprint]

我们希望将API 蓝图与模式一起使用。比方说，我们要指定对资源的 PUT 接受负载中的 Account 并且在同一资源上的 GET 返回一个 Account 负载。所以我需要指定在 GET 和 PUT 中使用 Account 并且我需要指定 Account 本身。我不知道在哪里指定它，规范的方式是什么？不幸的是，我无法在示例中找到它。

是否可以为对某个请求的每个响应指定描述？假设我们有一个请求

和 2 个回应

我想在这里指定描述（请在行下方注明注释+ Response）：

可能吗？

感谢您抽出宝贵时间，我有一个 POST 请求，我想在蓝图蜂房中记录，标题是这样的：

文本/html

_方法：POST

数据[用户][用户名]：

数据[用户][密码]：

数据[用户][记住]：0

http://d.pr/i/uRFx

我有这样的东西，但我不知道如何完成它：

任何想法？谢谢！

We have one existing API, which we're trying to build a Blueprint for, that requires certain request bodies to be URI-encoded JSON.

Is there some way to specify a body as "like this, but encoded"?

Existing (mere text) documentation just shows the JSON, along with an airy reminder to encode it before sending:

But with Blueprint—and especially with Blueprint at apiary.io—you really have to show the actual body. Which is completely unreadable:

But specifying the readable text in the Blueprint fails (returns a parameter error):

The real sticking point is when I have Apiary talk to my real server: the readable request fails (because it's not encoded), while the unreadable one succeeds (because, as required, it is).

我想知道是否可以在参数名称中包含方括号，这就是 Rails 对参数进行分组的方式。例如：

现在，如果我包含方括号，则不会呈现参数。

谢谢！

The “model” facility seems intended to reduce duplication — when specifying the requests and responses to various methods on a resource, the same body will frequently be specified multiple times. So one can define a “model” and then “refer” to it within various request and response “payload” sections.

So I’ve defined a model like so:

and I can then refer to it in various places:

which works great; the output includes the entire model body in place of the cross-reference.

However, I can’t figure out how to combine this reference with a request or response header.

I’ve tried various formats along these lines:

or

with no luck.

Is there any way to do this?

我想注释一些错误响应，如下所示：

但解析器（雪崩）似乎将注释解释为响应体。

我怎样才能注释这些响应并让雪崩明白它们是注释？

我想记录实际的 JSON 字段本身所代表的内容。

我已经记录了 GET 语句和参数，但这并没有提供给用户的完整文档。

因此，在下面的示例中，我将如何添加关于“OtherFields”的评论。这支持吗？或者我是否需要在其他地方制作配套文件。

我们正在研究使用 API 蓝图。在某些情况下，我们希望一个请求返回正确的响应，而另一个请求返回一个“错误”响应，例如 a 400 bad request，以便其他开发人员可以使用 apiary.io 上的模拟 API 处理这两种类型的响应并在他们的应用。

我在下面创建了一个完全任意的示例，

现在我想以某种方式添加对/thing/40

但我不确定如何使用 API 蓝图做到这一点。这在 apiary.io 上的“旧”样式下是可以实现的，但我们想继续使用新的语法

是否可以定义发生PUT to /asdf空请求正文时发生的情况与发生PUT to /asdf此请求正文时发生的情况{ "value": "somthing" }。