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

Posted 2023-02-16

【中文标题】在 OpenAPI / Swagger 文件中声明日期的正确方法是啥？

【英文标题】：What is the correct way to declare a date in an OpenAPI / Swagger-file?在 OpenAPI / Swagger 文件中声明日期的正确方法是什么？

【发布时间】：2018-08-28 23:02:18

【问题描述】：

在 swagger-file 对象中声明日期的正确方法是什么？我认为是：

  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

谢谢。

【参考方案1】：

OpenAPI Specification 说你必须使用：

类型：字符串 格式：日期#或日期时间

支持的模式在RFC 3339, section 5.6（实际上是 ISO 8601）中定义，示例在第 5.8 节中提供。所以对于date，值应该看起来像“2018-03-20”，对于date-time，应该是“2018-03-20T09:12:28Z”。因此，当使用date 或date-time 时，pattern 是不必要的，实际上应该省略。

如果您需要支持格式不同于 RFC 3339 的日期/时间，则不允许将您的参数指定为 format: date 或 format: date-time。相反，您应该使用适当的pattern 指定format: string。

最后，请注意"YYYY-MM-DD" 中的pattern 根据规范是无效的：pattern 必须是正则表达式，而不是占位符或格式字符串。

如果您违反上述任何规则来解决从 OpenAPI 规范生成 UI 的工具中的错误，您应该强烈考虑使用该工具提出这些错误，而不是生成无效的 OpenAPI 规范来解决此问题。

【讨论】：

指定 pattern 对于文档 UI（如 Swagger）最终用户很有用，因为格式 date 未明确显示（与 date-time 相反）。

有没有办法只提时间？

如果您的 API 不接受 OpenAPI 支持/建议格式的日期怎么办。你会改变你的 API 或规范吗？我将更改规范并使用 Pattern 而不是更改我的 API 签名。因此人们使用模式，或者只是在描述中提供它

【参考方案2】：

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

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

【讨论】：

我们如何在这里同时提供 DateTime？

【参考方案3】：

pattern 应该是一个正则表达式。这在OpenAPI Specification 中有说明。

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

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

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

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

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

我还建议将格式放在描述字段中，以便人类消费者更容易阅读。

【讨论】：

应该严格遵守为日期时间定义的格式，在显示时可以本地化为客户端格式，但对于 API，应该使用标准的 Internet 日期/时间格式

为 OpenAPI 规范定义的格式是标准的互联网日期/时间格式。但是，您可能会发现不是您编写或无权访问的 Web 服务不符合标准。在这些情况下，您仍然需要能够使用 OpenAPI 定义日期/时间格式。使用模式解决了这个问题。

【参考方案4】：

对于 Swagger 2.0

 /room-availability:
    get:
      tags:
      - "realtime price & availability"
      summary: "Check realtime price & availability"
      description: "Check realtime price & availability"
      operationId: "getRealtimeQuote"
      produces:
      - "application/json"
      parameters:
      - in: "query"
        name: "checkInDate"
        description: "Check-in Date in DD-MM-YYYY format"
        type: "string"
        pattern: "^(3[01]|[12][0-9]|0[1-9])-(1[0-2]|0[1-9])-[0-9]4$"
      - in: "query"
        name: "numOfGuests"
        description: "Number of guests"
        type: "integer"
        format: "int16"
      - in: "query"
        name: "numOfNightsStay"
        description: "number of nights stay"
        type: "integer"
        format: "int16"
      - in: "query"
        name: "roomType"
        description: "Room type"
        type: "string"
        enum:
        - "King Size"
        - "Queen Size"
        - "Standard Room"
        - "Executive Suite"
      - in: "query"
        name: "hotelId"
        description: "Hotel Id"
        type: "string"