我一直在使用 sphinx 来记录我们的 api。正如人们所预料的那样,我们的 api 中有些参数的值是一组受限的。例如,描述电视的帖子可能有一个“on”参数,并且相同的参数可能可用于在 GET 上进行过滤。
我的问题是我找不到描述有效参数值的内置方法。对于 bool 值,我可以将其放在括号中,但有些参数有 20 个有效输入值,有些参数有多个可能的输入参数集,具体取决于路径中多个变量点的值。例如:
myapi.com/<string:gameConsoleId>/games/<string:gameId>
在内部,我们不允许 gameConsoleId
或 gameId
使用任何可能的值。我们希望 gameConsoleId
是 PLAYSTATION
、XBOX
或 NINTENDO
。 gameId
也是如此。如果您将马里奥游戏传递到游戏机控制台,它应该返回一个错误,我们希望记录下来。
这是否表明 api 需要进行不同的设计,或者我只是缺少如何执行文档规范?
<小时/>更清楚地说,我正在尝试弄清楚如何在 Sphinx 中执行某些操作。具体来说,我正在寻找正确的语法、命令或规范来记录 api 端点的有效输入参数。我很清楚如何记录存在有效的输入参数。
查询字符串参数:
:query gameConsoleId: The type of game console
Json 参数(用于 POST 等):
:<json string gameConsoleId: The type of game console
我不清楚如何记录这些输入的有效值。我们定义了有效的输入,但我不清楚如何通过 Sphinx 进行交流。
例如,以下是 gameConsoleId 的有效输入:
[PLAYSTATION,XBOX,NINTENDO]
最佳答案
一个好的方法是查看流行且文档齐全的项目的现有文档,例如 Python 本身。 Python 文档使用多种方法来记录可以采用一组值之一的参数:
- 文本形式如 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.
- 值的项目符号列表,可能带有描述,如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
- 值表及其描述,如 format specification mini-language 所示.
编辑
本着这个答案的精神,numpy.array
的文档order
参数开始如下:
order : {'K', 'A', 'C', 'F'}, optional
这里我们看到允许的值被写为类型。也就是说,不是指定 order
采用 str
类型,然后解释允许哪些特定的 str
值,而是允许的值集被列为类型,用户推断类型为 str
。
关于python - Sphinx 描述 api 的有效输入值,我们在Stack Overflow上找到一个类似的问题: https://stackoverflow.com/questions/29974987/