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

1. введение

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

2. Чванство против ОАЗИС

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

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

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

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

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

Давайте определим сущность User с помощью 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

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

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

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

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

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

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

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

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

Используя OAS, мы можем описывать даты и в других форматах. Для этого давайте воспользуемся полем pattern :

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. Мы можем использовать стандартные форматы, предлагаемые открытым API, а также пользовательские шаблоны в соответствии с вашими потребностями. Как всегда, исходный код примера, который мы использовали, доступен на GitHub .