«1. Введение

В этом руководстве мы увидим, как объявлять даты в файле OpenAPI, в данном случае реализованном с помощью Swagger. Это позволит нам стандартизированно управлять датами ввода и вывода при вызове внешних API.

2. Swagger против OAS

Swagger — это набор инструментов, реализующих спецификацию OpenAPI (OAS), независимый от языка интерфейс для документирования RESTful API. Это позволяет нам понять возможности любого сервиса без доступа к исходному коду.

Для реализации этого в нашем проекте будет файл, обычно YAML или JSON, описывающий API с использованием OAS. Затем мы будем использовать инструменты Swagger для:

    редактирования нашей спецификации через браузер (редактор Swagger) автоматического создания клиентских библиотек API (Swagger Codegen) отображения автоматически сгенерированной документации (пользовательский интерфейс Swagger)

Пример файла OpenAPI содержит различные разделы, но мы сосредоточимся на определении модели.

3. Определение даты

Давайте определим сущность пользователя, используя OAS: 

components:
  User:
    type: "object"
    properties:
      id:
        type: integer
        format: int64
      createdAt:
        type: string
        format: date
        description: Creation date
        example: "2021-01-30"
      username:
        type: string

Чтобы определить дату, мы используем объект с:

    поле типа равно строке поле формата, которое указывает, как формируется дата

В этом случае мы использовали формат даты для описания даты createdAt. Этот формат описывает даты с использованием формата полной даты ISO 8601.

4. Определение даты-времени

Кроме того, если мы также хотим указать время, мы будем использовать дату-время в качестве формата. Давайте посмотрим на пример: 

createdAt:
  type: string
  format: date-time
  description: Creation date and time
  example: "2021-01-30T08:30:00Z"

В этом случае мы описываем дату и время, используя полный формат ISO 8601.

5. Поле шаблона

С помощью OAS мы можем описывать даты и в других форматах. Для этого воспользуемся полем шаблона: 

customDate: 
  type: string 
  pattern: '^\d{4}(0[1-9]|1[012])(0[1-9]|[12][0-9]|3[01])$'
  description: Custom date 
  example: "20210130"

Понятно, что это менее читаемый метод, но зато самый мощный. Действительно, мы можем использовать любое регулярное выражение в этом поле.

6. Заключение

В этой статье мы рассмотрели, как объявлять даты с помощью OpenAPI. Мы можем использовать стандартные форматы, предлагаемые OpenAPI, а также пользовательские шаблоны в соответствии с нашими потребностями. Как всегда, исходный код примера, который мы использовали, доступен на GitHub.