gpt4 book ai didi

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

转载 作者:太空宇宙 更新时间:2023-11-03 17:44:45 25 4
gpt4 key购买 nike

我一直在使用 sphinx 来记录我们的 api。正如人们所预料的那样,我们的 api 中有些参数的值是一组受限的。例如,描述电视的帖子可能有一个“on”参数,并且相同的参数可能可用于在 GET 上进行过滤。

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

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

在内部,我们不允许 gameConsoleIdgameId 使用任何可能的值。我们希望 gameConsoleIdPLAYSTATIONXBOXNINTENDOgameId 也是如此。如果您将马里奥游戏传递到游戏机控制台,它应该返回一个错误,我们希望记录下来。

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

  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

    关于python - Sphinx 描述 api 的有效输入值,我们在Stack Overflow上找到一个类似的问题: https://stackoverflow.com/questions/29974987/

    25 4 0
    Copyright 2021 - 2024 cfsdn All Rights Reserved 蜀ICP备2022000587号
    广告合作:1813099741@qq.com 6ren.com