问题标签 [apiblueprint]

I am trying out API Blueprint and found some things, which are not quite clear to me.

1. How can I document POST body parameters?

There is + Parameters but it just documents query parameters. If I now want to describe a POST API I can't document POST parameters (application/x-www-form-urlencoded). The same goes for JSON (see #3).

2. Is there a way to add a description to a response?

I tried

But this just adds the text as the body response.

3. Describe the different fields of my response

If I return JSON I want to describe each field separately, its type and its purpose. Is there a way to do that?

Thanks!

I want to specify the various exceptions/errors that have to be returned while making an API call. How do I achieve this with Apiary.

我有一张桌子：

我希望表格显示在我的 Markdown 文件的中心，而不是左对齐。我不是要对齐文本，而是要对齐整个表格本身。我需要求助于 HTML/CSS 来实现我想要的吗？

这是一个 Apiary.io 项目。

我想记录一个多部分请求，如下所示：

重现相同请求的 Acurl将类似于：

我是 API Blueprint 的新手，所以请原谅我的天真。我正在尝试格式化一些参数，例如 Aglio 示例中给出的：

但是，为参数名称显示的只是参数的索引。这是 Atom API-Display 包中的显示：https ://atom.io/packages/api-blueprint-preview 。

如何让它显示参数的名称？

这个

生成    

现在这个：

生成    

为什么单个资源不是 Apiary 目录的一部分？

我在 Apiary 中定义了一个 API 合同，并且我正在使用资源模型语法来启用有效负载的重用。

Apiary 呈现的文档仅显示模型名称（例如，响应 200 返回一个 [Foo][]） - 没有任何关于 Foo 是什么的进一步详细信息，或任何查看 Foo 模型中属性的链接。

给定一个模型，我如何在渲染的文档中查看它的属性？

更新
合同的相关部分如下：

我想为 Apiary 参数定义选项，我目前在描述中列出它们：

• 测量= m（可选，字符串，m）...测量例如m =米，km =公里，yd =码，mi =英里

我的 API 返回完整的主机 URL，在 Apiary 中，每个用户都有自己的模拟服务器私有 URL。

有没有办法在响应正文中使用这个 URL？

现在我在响应正文中使用我自己的 URL。

我有一个大型模型，我将其用于资源上的 GET 和 PUT。该模型包括一个“审计”对象，如下所示：

这显然是资源的只读部分 - 有没有办法在合同模型中显示这一点，所以“审计”出现在 GET 响应表示而不是 PUT 请求表示？

我能看到的唯一替代方法是将模型复制到 PUT 的主体中并删除只读部分 - 但这消除了拥有可跨不同方法重用的单个模型的好处。