Как стать автором
Обновить
0
Typeable
Functional programming, High assurance, Consulting

В чем польза формальных спецификаций вроде OpenAPI?

Время на прочтение3 мин
Количество просмотров10K


В этой статье хочу рассказать, что такое OpenAPI и зачем он может быть нужен.


Ваши покемоны


Ваше положение: у вас два разработчика. Один разрабатывает бекенд вашего продукта, а другой – фронтенд.


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



Архитектор разрабатывает идеальный API, описывает его в одном большом документе и выдает разработчикам.



Каждый разработчик берет документ, описывающий API, внимательно его читает, и реализует описанный API.


Пять раз отмерь, один раз отрежь


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



Давайте теперь посмотрим, что должно произойти чтобы запросы на фронтенде и бекенде совпадали:


  1. Бекенд разработчик не допустил ошибок в реализации API
  2. Бекенд разработчик правильно понял описание API от архитектора
  3. Фронтенд разработчик не допустил ошибок в реализации API
  4. Фронтенд разработчик правильно понял описание API от архитектора

Если хоть в одном из этих пунктов кто-то допустит ошибку, то весь ваш проект будет падать. И это с предположением, что архитектор не допускает ошибок (спойлер: таких нет).


Нужно отдельно отметить, что большая ноша ложится на человеческое понимание и человеческую коммуникацию технических деталей. Человеческое понимание в целом довольно трудно дебажить и тестировать.


Люди – самое слабое звено


Закономерным в сложившейся ситуации кажется желание минимизировать человеческий фактор в разработке API. Хочется не иметь человеческого фактора с того момента, как архитектор описал API в своем документе. (Вообще, хочется и от ошибок архитектора избавиться, но технологии до такого пока не дошли.)


Очевидно, что чтобы такое сделать, нужно чтобы выхлопом архитектора был не человеко-читаемый документ, а компьютеро-читаемый документ – своего рода формальная спецификация конкретного API. Если у нас будет такое описание API, мы можем как минимум попытаться возложить последующие шаги на автоматизацию.


Для каждого языка программирования при использовании какого-то конкретного фреймворка обычно не так много способов сделать "каноничную" реализацию какого-то HTTP API. Обычно в фреймворках не так много способов сделать запрос с JSON объектом в теле, и не так много способов считать целое число из пути запроса.


OpenAPI


Было бы здорово иметь возможность один раз описать свой HTTP API, и из этого описание получить совпадающие каркасы для реализации бекенда и фронтенда, которые, из-за отсутствия человека в цепочке, будут с большей вероятностью совпадать. (При условии, что генерация этих каркасов реализована без ошибок, но это, на самом деле, более простая задача.)


О, чудо! Такое уже придумали! И называется оно OpenAPI!


OpenAPI позволяет формально описывать HTTP API в виде YAML файлов. Довольно обширный пример можно посмотреть на editor.swagger.io. Там можно смотреть исходный YAML и человеко-читаемую HTML страничку одновременно.


Если изначальную спецификацию архитектор опишет в виде OpenAPI спецификации, то все взаимодействие между бекендом и фронтендом можно будет сгенерировать автоматически, и оно будет гарантированно совпадать. Таким образом мы вообще исключаем из цепочки человеческий фактор!



Больше чем просто кодогенерация


Кодогенерация – это лишь одно из применений OpenAPI. OpenAPI – открытый формат описания HTTP API, не завязанный на какую-то конкретную экосистему. Он позволяет обмениваться точным описанием API между системами, которые в иных условиях требовали бы ручной "синхронизации" API.


Есть большое количество инструментов, работающих на базе OpenAPI спецификаций. Хорошим ресурсом таких проектов является openapi.tools. Там представлены такие проекты как: GUI редакторы спецификаций, генераторы тестовых серверов по спецификациям, поиск уязвимостей по спецификации, и многое другое!


Используя OpenAPI можно не только повысить точность описания своих API, но и получить доступ к большому числу инструментов, которые помогут в разработке проекта.


Читайте в нашем блоге:


  1. Когда стоит выбирать микросервисы
  2. Параллельные вселенные для вашего CI/CD пайплайна в Octopod
  3. Антирегрессионное тестирование – минимизируйте затраты
  4. Property-based тестирование с QuickCheck

Версия на английском языке: https://typeable.io/blog/2021-09-06-api-diff.html

Теги:
Хабы:
Всего голосов 15: ↑8 и ↓7+3
Комментарии1

Публикации

Информация

Сайт
typeable.io
Дата регистрации
Дата основания
Численность
11–30 человек
Местоположение
Россия

Истории