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 Specification表示你应该使用：

type: string
format: date  # or date-time

使用的模式在RFC 3339, section 5.6中定义因此，对于date，该值应该类似于＆＃34; 2018-03-20＆＃34;并为date-time＆＃34; 2018-03-20T09：12：28Z＆＃34;。

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

Answer 2

模式应为正则表达式。 OpenAPI Specification中对此进行了说明。

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

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

OpenAPI 2.0：此对象基于JSON Schema Specification Draft 4，并使用   它的预定义子集。

OpenAPI 3.0：此对象是JSON模式规范Wright Draft 00的扩展子集。

如果Web服务公开的日期或日期时间不符合RFC3339中所述的Internet日期/时间格式，则 date 和 date-时间对于 format 字段无效。该属性必须定义为具有 type 等于 string 的 type ，而不使用 format 。相反，可以使用 pattern 给出定义日期或日期时间模式的正则表达式。这使客户端工具可以自动分析日期或日期时间。

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

Answer 3

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

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

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

3 个答案: