在OpenAPI/Swagger文件中声明日期的正确方法是什么？

Question

在swagger文件对象中声明日期的正确方法是什么？我认为它是:

  startDate:
    type: string
    description: Start date
    example: "2017-01-01"
    format: date

但我看到很多这样的声明:

  startDate:
    type: string
    description: Start date
    example: "2017-01-01"
    format: date
    pattern: "YYYY-MM-DD"
    minLength: 0
    maxLength: 10

谢谢.

Answer 1

该OpenAPI的规范说,你应该使用:

type: string
format: date  # or date-time

要使用的模式在RFC 3339的5.6节中定义.
因此,date该值应该看起来像"2018-03-20"和date-time"2018-03-20T09:12:28Z".

我不知道为什么人们明确指定,pattern因为它是在format定义中隐式定义的.

Answer 2

模式应该是一个正则表达式。这在OpenAPI 规范 中有说明。

模式（根据 ECMA 262 正则表达式方言，此字符串应该是有效的正则表达式）

这是因为 OpenAPI 对象基于 JSON Schema 规范。

OpenAPI 2.0：此对象基于 JSON 模式规范草案 4 并使用它的预定义子集。

OpenAPI 3.0：此对象是 JSON Schema Specification Wright Draft 00 的扩展子集。

如果 Web 服务公开的日期或日期时间不符合RFC3339 中描述的 Internet 日期/时间格式，则日期和日期时间不是格式字段的有效值。该属性必须定义为类型等于string而不使用format。相反，模式可用于提供定义日期或日期-时间模式的正则表达式。这允许客户端工具自动解析日期或日期时间。

我还建议将格式放在描述字段中，以便人类消费者可以更轻松地阅读它。

Answer 3

OpenAPI 3 的示例基于此处的文档：

\n

https://swagger.io/docs/specification/data-models/data-types/

\n

可选的格式修饰符用作字符串内容和格式的提示。OpenAPI 定义了以下内置字符串格式：

\n

date \xe2\x80\x93 RFC 3339 第 5.6 节定义的完整日期表示法，例如 2017-07-21

\n

date-time \xe2\x80\x93 RFC 3339 第 5.6 节定义的日期时间表示法，例如 2017-07-21T17:32:28Z

\n

BookingNoteRequest:\n  type: object\n  properties:\n    note:\n      type: string\n    postedDate:\n      type: string\n      format: date\n      example: \'2022-07-01\'\n    postedTime:\n      type: string\n      format: date-time\n      example: \'2017-07-21T17:32:28Z\'\n

\n

如果日期或日期时间格式不遵循 RFC 3339 定义的标准，则应删除格式字段并添加定义格式的正则表达式的模式字段。

\n

Answer 4

在 Open API swagger 文件中声明日期的正确示例：

    properties:
      releaseDate:
        type: date
        pattern: /([0-9]{4})-(?:[0-9]{2})-([0-9]{2})/
        example: "2019-05-17"