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.

回答1:

The OpenAPI Specification says that you should use:

type: string
format: date  # or date-time

The pattern to use is defined in RFC 3339, section 5.6.
So for date the value should look like "2018-03-20" and for date-time "2018-03-20T09:12:28Z".

I don't know why people specify the pattern explicitly because it is implicitly defined in the format definition.

回答2:

pattern should be a regular expression. This is stated in the OpenAPI Specification.

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

This is because OpenAPI objects are based off the JSON Schema specification.

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.

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 date and date-time are not valid values for the format field. The property must be defined as having a type equal to string without using format. Instead, pattern 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.

来源：https://stackoverflow.com/questions/49379006/what-is-the-correct-way-to-declare-a-date-in-an-openapi-swagger-file

标签

swagger

openapi