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

Question

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

147

在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

- Patrick Savalle

5个回答

20

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

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

- Filipe Bezerra de Sousa

我们怎样可以在这里同时给出日期和时间？ - PAA

4

你为什么要在每个字段周围加上()？第二组为什么被忽略了？谢谢。 - Pastello

5

使用 format: date 而不是 pattern，更易于阅读。如果想要使用正则表达式匹配不同的日期格式，请勿使用 type: date，而应改为使用 type: string。 - Abel

规范指示只有在日期不遵循RFC3339中定义的标准时才应使用模式。在这种情况下，类型应该是字符串而不是日期。 - Kriil

10

pattern 应为正则表达式。这在 OpenAPI 规范中有说明。

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 中描述的互联网日期/时间格式的日期或日期时间，则 date 和 date-time 不是 format 字段的有效值。属性必须定义为具有等于 string 的 type，而不使用 format。相反，可以使用 pattern 来提供定义日期或日期时间模式的正则表达式。这允许客户端工具自动解析日期或日期时间。

我还建议将格式放在说明字段中，以便人类用户更轻松地阅读。

- Kriil

在编程中，应该严格遵守日期时间格式的定义。在显示时可以本地化到客户端格式，但对于 API，则应使用标准的互联网日期/时间格式。 - Pankaj Upadhyay

5

OpenAPI规范定义的格式是标准的互联网日期/时间格式。但是，您可能会遇到一些不符合标准的Web服务，这些服务可能是由其他人编写或者您无法访问。在这种情况下，您仍然需要使用OpenAPI来定义日期/时间格式。使用模式可以解决这个问题。 - Kriil

7

OpenAPI 3的一个示例基于此文档：

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

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

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

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

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

如果日期或日期时间格式不遵循 RFC 3339 所定义的标准，则应删除“格式”字段，并添加“模式”字段，其中包含一个正则表达式来定义格式。

- sendon1982

-1

针对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"

- amitsriv99

网页内容由stack overflow 提供, 点击上面的

可以查看英文原文，
原文链接

- Pascal · Accepted Answer

OpenAPI规范指出您必须使用：

type: string
format: date # or date-time

OpenAPI使用的互联网日期/时间标准在RFC 3339，第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。相反，您应该指定type：string并使用适当的pattern，然后删除format。

最后，需要注意的是，"YYYY-MM-DD" 的 pattern 是不符合规范的： pattern 必须是一个正则表达式，而不是一个占位符或格式字符串。