在API蓝图中记录互斥查询参数(Documenting Mutually Exclusive Query Parameters in API Blueprint)

在API蓝图中记录互斥查询参数(Documenting Mutually Exclusive Query Parameters in API Blueprint)

我正在记录一个公共API，它有一个名为/findGuild的方法，它接受一个必需的key参数和一个以下参数：

byPlayer byName

它必须有byPlayer或byName ; 我的问题是： 我如何表明byPlayer和byName是互斥的，但一个是强制性的？

---

现在，我的.apib有以下资源：

### GET /findGuild{?byName,byPlayer,key} + Parameters + byName: `YourGuild` (string, optional) - Search for the Guild by its name. + byPlayer: (string, optional) - Search for Guild by a player. Does not seem to work. + key: `ffffffff-ffff-ffff-ffff-ffffffffffff` (string, required) - The user's API key. + Response 200 (application/json) + Attributes (object) + guild (string) - The guild id or null. + success (boolean) - Should be true. + Body { "guild": "ffffffffffffffffffffffff", "success": true }

I'm documenting a public API that has a method named /findGuild that takes a mandatory key parameter and one of the following parameters:

byPlayer byName

It must have either byPlayer or byName; My question is: How do I indicate that byPlayer and byName are mutually exclusive, but one is mandatory?

---

Right now, I have the following in my .apib for this Resource:

### GET /findGuild{?byName,byPlayer,key} + Parameters + byName: `YourGuild` (string, optional) - Search for the Guild by its name. + byPlayer: (string, optional) - Search for Guild by a player. Does not seem to work. + key: `ffffffff-ffff-ffff-ffff-ffffffffffff` (string, required) - The user's API key. + Response 200 (application/json) + Attributes (object) + guild (string) - The guild id or null. + success (boolean) - Should be true. + Body { "guild": "ffffffffffffffffffffffff", "success": true }

最满意答案

我担心（但不完全确定）API Blueprint目前无法表达这种关系。

我可以肯定地说，根据公共路线图 ，URI参数将被替换为MSON对象 ，它支持您要求的场景 。

希望能帮助到你！

I am afraid (but not totally sure) API Blueprint is not capable of expressing this kind of relationship at the moment.

What I can surely tell you is that, according to public roadmap, URI Parameters will be replaced with an MSON object, which supports the scenario you're asking for.

Hope it helps!