使用API​​蓝图记录查询参数 [英] Documenting query parameters with API Blueprint

问题描述

我正在尝试在API Blueprint中记录查询参数，但是我不确定是否正确完成了该操作.该资源如下所示:

I'm trying to document a query parameter in API Blueprint, but I'm not entirely sure if I have done it correctly. The resource looks like this:

DELETE http://baasar.apiary-mock.com/user/{appId}/{userId}

该请求将停用用户，而以下请求将删除用户对象:

That request would deactivate the user while the following would delete the user object:

DELETE http://baasar.apiary-mock.com/user/{appId}/{userId}?force=true

这是我为此所做的蓝图减价:

This is the Blueprint markdown I have for this:

## User [/user/{appId}/{userId}]
Handle user objects

+ Parameters
    + appId (required, number, `1`) ... Application ID (`appId`)
    + userId (required, number, `1`) ... Numeric `userId` of the User object to manage

### Remove an User [DELETE]
+ Parameters
    + force (optional, boolean, `false`) ... Set to `true` to remove instead of deactivate

+ Response 204

但是，当使用Apiary渲染时，我仅在参数列表中看到force，但是现在它显示在示例URL中.仅仅是我误解了GUI还是应该以其他方式记录查询参数?

However, when rendering this with Apiary I only see force in the list of parameters, but it is now shown in the example URL. Is that just me misunderstanding the GUI or should query parameters be documented in another way?

推荐答案

您的蓝图非常好，问题在于当前的Apiary文档无法正确处理URI参数.

Your blueprint is perfectly fine, the problem is that the current Apiary documentation does not handle URI parameters correctly.

请尝试使用新文档出?它应该正确处理URI参数.

Could you please try the new documentation out? It should handle URI parameters properly.

正确的URI模板应为:

The correct URI Template should be:

http://baasar.apiary-mock.com/user/{appId}/{userId}{?force}

这篇关于使用API​​蓝图记录查询参数的文章就介绍到这了，希望我们推荐的答案对大家有所帮助，也希望大家多多支持IT屋！