Каков правильный способ объявить дату в объекте 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
Благодарю.
Спецификация OpenAPI говорит, что вы должны использовать:
type: string
format: date # or date-time
Шаблон для использования определен в RFC 3339, раздел 5.6.
Таким образом, для date значение должно выглядеть как "2018-03-20", а для date-time "2018-03-20T09: 12: 28Z".
Я не знаю, почему люди указывают pattern явно, потому что он неявно определен в определении format.
шаблон должен быть регулярным выражением. Это указано в спецификации OpenAPI.
pattern (Эта строка ДОЛЖНА быть допустимым регулярным выражением, согласно диалекту регулярного выражения ECMA 262)
Это связано с тем, что объекты OpenAPI основаны на спецификации схемы JSON.
OpenAPI 2.0: этот объект основан на черновом варианте спецификации схемы JSON 4 и использует его предопределенное подмножество.
OpenAPI 3.0: этот объект является расширенным подмножеством спецификации JSON схемы Wright Draft 00.
Если веб-служба предоставляет дату или дату-время, которые не соответствуют формату даты/времени в Интернете, описанному в RFC3339, тогда дата и время-дата не являются допустимыми значениями для поля формата. Свойство должно быть определено как имеющее тип, равный строке, без использования формата. Вместо этого шаблон может использоваться для создания регулярного выражения, которое определяет шаблон даты или времени. Это позволяет клиентскому инструменту автоматически анализировать дату или дату-время.
Я также рекомендую указывать формат в поле описания, чтобы пользователи могли легче его прочитать.