在 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 Specification 说你必须使用：

类型：字符串格式：日期#或date-time

支持的模式在 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 的方式支持 dates/times 格式，您 不允许 将您的参数指定为 format: date 或format: date-time。相反，您应该使用适当的 pattern.

指定 format: string

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

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

Answer 2

pattern 应该是正则表达式。 OpenAPI Specification.

中说明了这一点

pattern (This string SHOULD be a valid regular expression, according to the ECMA 262 regular expression dialect)

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

OpenAPI 2.0: This object is based on the JSON Schema Specification Draft 4 and uses a predefined subset of it.

OpenAPI 3.0: This object is an extended subset of the JSON Schema Specification Wright Draft 00.

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

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

Answer 3

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

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

Answer 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"

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

What is the correct way to declare a date in an OpenAPI / Swagger-file?

swagger

openapi

对于 Swagger 2.0