API蓝图中的响应描述和POST参数 [英] Response description and POST parameters in API Blueprint

问题描述

我正在尝试API蓝图，发现了一些我不太清楚的东西.

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

有+ Parameters，但仅记录查询参数.如果现在我要描述POST API，则无法记录POST参数(application/x-www-form-urlencoded). JSON也是如此(请参阅#3).

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).

我尝试了

+ Response 403
If the request request is made with HTTP instead of HTTPS.

但这只是将文本添加为​​正文响应.

But this just adds the text as the body response.

如果我返回JSON，我想分别描述每个字段，其类型和用途.有办法吗?

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

谢谢！

推荐答案

让#1和#3密切相关，让我们共同看待它们:

Lets look #1 and #3 together as they are closely related:

当前，没有专门的语法来讨论

Currently there is no dedicated syntax for discussing the actual fields of a payload (model, response or request).

目前由您决定如何使用所需的Markdown语法对其进行描述.

For now it is up to you how do you describe it using any Markdown syntax you like.

计划提供Markdown语法来讨论这些字段/参数，如下所示:

The plan is to provide a Markdown syntax for discussing these fields / parameters like this:

JSON:

{
    "id": 1,
    "name": "A green door",
    "price": 12.50,
    "tags": ["home", "green"]
}

及其在蓝图中的描述:

- id: 1 (integer) - The unique identifier for a product
- name: A green door (string) - Name of the product
- price: 12.50 (number)
- tags: home, green (optional, array of strings)

我目前正在为此工作.可以在此处找到详细信息.

I am currently working on this. More details can be found here.

您已经可以添加任何降价标记对有效载荷进行格式化的讨论

You can already add any markdown formatted discussion to a payloads

# Resource [/r]
## List [GET]
+   Response 200

    This response will list the R

    + Body

            { ... }

此处有更多信息: https://stackoverflow.com/a/19433269/634940

注意:为了使描述正确显示在Apiary中，您可能需要使用

Note: In order for the description to appear correctly in Apiary you might need to use the New Apiary Rendered documentation

这篇关于API蓝图中的响应描述和POST参数的文章就介绍到这了，希望我们推荐的答案对大家有所帮助，也希望大家多多支持IT屋！