Рубрики
Без рубрики

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

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

Автор оригинала: baeldung.

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 .