Даты в файлах OpenAPI

1. Введение

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

2. Чванство против ОАГ

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 .