问题描述
我正在尝试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参数的文章就介绍到这了,希望我们推荐的答案对大家有所帮助,也希望大家多多支持!