Sphinx 将有效输入值描述为 api

Question

我一直在使用 sphinx 来记录我们的 api。正如人们可能预料的那样，我们的 api 中有某些参数，其值是一个限制集。例如，描述电视的 post 可能有一个 "on" 参数，并且相同的参数可能可用于 GET 上的过滤。

我的问题是找不到描述有效参数值的内置方法。对于 bool，我可以将它放在括号中，但有些参数有 20 个有效输入值，有些参数有多个可能的输入参数集，具体取决于路径中多个变量点的值。例如：

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

在内部，我们不允许 gameConsoleId 或 gameId 有任何可能的值。我们希望 gameConsoleId 成为 PLAYSTATION，或 XBOX，或 NINTENDO。 gameId也是如此。如果您将 mario 游戏传递给 playstation 控制台，它应该 return 一个错误，我们想记录下来。

这是否表明 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 文档使用多种方法来记录可以采用一组值中的一个的参数：

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

Table 个值及其描述如 format specification mini-language.

Sphinx 将有效输入值描述为 api

Sphinx describe valid input values to api

python

api

documentation-generation

flask

python-sphinx