在 Apiary 中表示输入参数是日期/时间的正确格式是啥？

Posted 2023-03-30

【中文标题】在 Apiary 中表示输入参数是日期/时间的正确格式是啥？

【英文标题】：What is the correct format for denoting that an input parameter is a date/time in Apiary?在 Apiary 中表示输入参数是日期/时间的正确格式是什么？

【发布时间】：2015-07-09 15:20:00

【问题描述】：

我正在编辑我正在处理的项目的一些 Apiary 文档，并且需要指出我的 API 调用之一的参数是日期时间字符串。 Apiary 似乎对这个参数的格式感到窒息，所以我想知道在 Apiary 中记录这个参数的建议方法是什么。

为了演示，我从 Apiary 获取了标准的默认文档，并修改了 Choice 文档以获取日期时间对象，如下所示：

## Choice [/questions/question_id/choices/choice_id/datetime]

+ Parameters
    + question_id: 1 (required, number) - ID of the Question in form of an integer
    + choice_id: 1 (required, number) - ID of the Choice in form of an integer
    + datetime: 2015-05-05T12:30:00 (optional, date) - The date/time (ISO8601 format) associated with this choice

这样的最终结果是以下文本：

datetime
05-05T12:30:00 (optional, date) - The date/time (ISO8601 format) that all returned events should be greater than or equal to Example: 2015.

这显然是错误的，甚至记下示例值。破折号 (-) 是一个特殊字符，在这里会引起悲伤。正确执行此操作的推荐方法是什么？

【参考方案1】：

您应该将be able to use backticks 作为转义序列。另请注意there is no such type as date。你应该使用string:

+ datetime: `2015-05-05T12:30:00` (optional, string) - The date/time (ISO8601 format) associated with this choice

【讨论】：

如果日期是后端自动生成的呢？ （自动时间戳）

我不明白评论。最初的问题是关于一个设计文档，其中指定了 HTTP 请求或响应中的内容。无论您的后端生成什么，正确描述它都取决于您。它可能是字符串或数字。

我基本上想知道是否有办法指定一个不需要但由支持自动生成的字段

现在我了解到每个方法（GET、POST、PUT）都有自己的文档，这对我来说更有意义，因为“必需”意味着每个方法基本上都有其他内容

在请求中，您不指定此类字段。作为回应，您会将其标记为required（始终存在）或fixed（如果该值是常量 - 通常不适用于时间戳），并且您会在描述中注意到该字段是由服务器自动生成的并且是只读的。