在 API 蓝图中记录互斥查询参数

Question

我正在记录一个 public 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
            }

Answer 1

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

我可以肯定地告诉你的是，根据你的要求 public roadmap, URI Parameters will be replaced with an MSON object, which supports the scenario。

希望对您有所帮助！

在 API 蓝图中记录互斥查询参数

Documenting Mutually Exclusive Query Parameters in API Blueprint

apiblueprint