python - Sphinx 描述 api 的有效输入值

Question

我一直在使用 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]

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.

值的项目符号列表，可能带有描述，如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。