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

What is the correct way to declare a date in a swagger-file object? I would think it is:

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

But I see a lot of declarations like these:

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

Thanks.

190917 次浏览
小开
最佳答案

The OpenAPI 规范 says that you must use:

type: string format: date # or date-time

支持的模式在 RFC 3339第5.6节(有效的 ISO 8601)中定义，例子在5.8节中提供。因此，对于 date值应该类似于“2018-03-20”，而对于 date-time，则应该类似于“2018-03-20T09:12:28Z”。因此，当使用 date或 date-time，pattern是不必要的，事实上，应该省略。

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

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

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

小开

Pattern 应该是一个正则表达式。

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

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

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

OpenAPI 3.0: 这个对象是 JSON 模式规范 Wright 草案00的扩展子集。

If a web service exposes a date or a date-time that doesn't conform to the Internet Date/Time Format described in RFC3339, then 约会 and 约会时间 are not valid values for the 格式 field. The property must be defined as having a 类型 equal to 绳子 without using 格式. Instead, 模式 can be used to give a regular expression that defines the date or date-time pattern. This allows a client tool to automatically parse the date or date-time.

I also recommend putting the format in the description field so human consumers can read it more easily.

小开

A correct example of declaring date in an Open API swagger file:

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

为了斯威格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 3的一个例子基于以下文档:

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

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

Date -由 RFC3339第5.6节定义的全日期表示法，例如2017-07-21

Date-time -由 RFC3339第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'

提交答案