Недостатки OpenAPI — тип и формат

Как бы вы определили параметр/поле типа «long»? Это просто, верно? Вы просто объявляете параметр/поле с его типом:

Java и C#: long the_field.

Kotlin: the_field: Long

Go: int64 the_field

Rust: the_field: i64

Каждый язык программирования имеет «оптимизированный» способ кодирования параметров/полей. Это понятно и ожидаемо, поскольку написание кода в основном состоит из определения полей и параметров функций.

Формат

Теперь, как бы вы сделали это в OpenAPI и JSON Schema? Это должно быть просто, учитывая, что long довольно широко используется, верно?

Вам понадобится поле format:

the_field:
  type: integer
  format: int64
Войти в полноэкранный режим Выйти из полноэкранного режима

Зачем нам нужны два поля: type и format? Почему мы не можем просто указать type: int64? Тип int64 не входит в число типов, поддерживаемых OpenAPI и JSON Schema: string, number, integer, object, array, boolean, null. Все остальные типы должны использовать формат для уточнения.

Можно отметить, что такая ограниченная система типов унаследована от самого JSON. Это означает, что OpenAPI и JSON Schema предназначены для схематизации только тех типов, которые могут встретиться в JSON. Однако это не так. Тип integer не существует ни в JSON, ни в JavaScript, поэтому спецификация уже придумывает новые типы. Почему бы не придумать хотя бы все базовые типы, например, int64? Ведь int64 не одинок, есть и другие полезные типы.

Кроме того, один и тот же синтаксис полей type и format используется как в схемах JSON, так и в параметрах операций. На определение параметров операций HTTP не накладывается никаких ограничений системы типов JavaScript. Параметры операций (запрос, заголовок, форма-данные, cookies) должны быть сериализуемы в строку (или массив строк). Они не имеют ничего общего с типами, поддерживаемыми в JSON.

Вот форматы, упомянутые в документации OpenAPI: int32, int64, float, double, byte, binary, date, date-time, uuid.

Да, именно так — спецификация API не может использовать практически ни один тип без указания формата. Поле format кажется более полезным, чем поле type.

Краткость

Наконец, то, как OpenAPI и JSON Schema разработали встроенные типы, заставляет разработчиков писать больше строк или использовать дополнительные структуры:

# There are 3 lines to define the field
the_field1:
  type: integer
  format: int64

# Additional structure
the_field2: { type: integer, format: int64 }
Вход в полноэкранный режим Выход из полноэкранного режима

В приведенном примере нет флагов required, указанных для полей, которые обсуждались в предыдущем посте. Указание флагов required вообще вместе с format делает поле еще длиннее.

Вот возможное исправление этой конструкции:

the_field1: int64
the_field2: uuid
Войти в полноэкранный режим Выйти из полноэкранного режима

Это будет означать «the_field имеет тип int64«, как в любом нормальном языке программирования. Тип, указанный выше, является логическим. Это не просто какой-то тип в протоколе сериализации. Тип имеет немного больше смысла — что хранится в этом поле? что это за число? что это за строка? Это все вопросы, на которые должны отвечать хорошие спецификации. Логический тип по-прежнему однозначно определяет технический тип поля JSON: uuid -> string, int64 -> integer, datetime -> string….

Эта конструкция может быть использована для пометки полей как необязательных (опциональных):

the_field: optional<int64>
Войти в полноэкранный режим Выход из полноэкранного режима

Альтернативный вариант:

the_field: int64?
Войти в полноэкранный режим Выйти из полноэкранного режима

Код выше не использует ни type, ни format, ни required. Мы перешли к мясу определения поля без каких-либо дополнительных указаний. Это очень похоже на то, как определяются интерфейсы, включая поля и параметры, в языках программирования. Они намеренно разработаны для использования коротких определений. Краткость важна для лучшего написания и читабельности спецификации.

Такие причуды, как определения format и type, очень странны для разработчиков, которые привыкли к более удобным способам определения параметров/полей. Я думаю, что в целом это отталкивает разработчиков от работы со спецификациями. Читайте о других недостатках спецификаций OpenAPI в этой серии статей.

Оцените статью
devanswers.ru
Добавить комментарий