Sphinx描述api的有效输入值

Question

我一直在用斯芬克斯来记录我们的api。正如人们所期望的，我们的api中有一些参数，其值是一个受限集。例如，对于描述电视的post，可能有一个“on”参数，并且相同的参数可能可用于对GET进行筛选。

我的问题是我找不到一种内置的方法来描述有效的参数值。对于bools，我可以将它放在parens中，但是有些参数有20个有效的输入值，有些参数根据路径中多个变量点的值，有多个可能的输入参数集。例如：

myapi.com/<string:gameConsoleId>/games/<string:gameId>

在内部，我们不允许^{{cd1>}或^{{cd2>}的任何可能值。我们希望^{cd1>}是^{{cd4>}，或^{{cd5>}，或^{cd6>}。^{cd2>}也是如此。如果您将mario游戏传递给playstation控制台，它应该返回一个错误，我们希望记录此错误。

这是api需要不同设计的标志，还是我只是错过了如何执行文档规范？

---

更清楚的是，我正在努力想办法在斯芬克斯做点什么。具体来说，我正在寻找正确的语法、命令或规范，以将有效的输入参数记录到api端点。我清楚地知道如何记录是否有有效的输入参数。

查询字符串参数：

^{pr2}$

Json参数（用于POST等）：

^{pr3}$

我不清楚的是如何记录这些输入的有效值。我们定义了有效的输入，我不清楚如何通过斯芬克斯来传达。

例如，以下是gameConsoleId的有效输入：

^{pr4}$

Answer 1

一个好的方法是查看一个流行的、有良好文档记录的项目的现有文档，比如Python本身。Python文档使用几种方法来记录参数，这些参数可以采用一组值中的一个：

1. 文本形式如ZipFile：

The mode parameter should be 'r' to read an existing file, 'w' to truncate and write a new file, or 'a' to append to an existing file.

1. 值的项目符号列表，可能带有说明，如os.chmod：

mode may take one of the following values (as defined in the stat module) or bitwise ORed combinations of them:

• stat.S_ISUID
• stat.S_ISGID
• stat.S_ENFMT

1. 值及其描述表，如format specification mini-language。在