В этой статье хочу рассказать, что такое OpenAPI и зачем он может быть нужен.
Ваши покемоны
Ваше положение: у вас два разработчика. Один разрабатывает бекенд вашего продукта, а другой – фронтенд.
У вас есть идея для нового супер-классного приложения и вы хотите реализовать его как можно быстрее, поэтому вы призываете опытного архитектора чтобы он заранее спроектировал идеальный API, под который можно будет одновременно разрабатывать фронтенд и бекенд.
Архитектор разрабатывает идеальный API, описывает его в одном большом документе и выдает разработчикам.
Каждый разработчик берет документ, описывающий API, внимательно его читает, и реализует описанный API.
Пять раз отмерь, один раз отрежь
В конечном итоге мы хотим получить фронтенд и бекенд, каждый из которых будет реализовывать одни и те же запросы (фронтенд отправлять, а бекенд обрабатывать). В идеале, эти запросы должны еще и соответствовать тому, что описал архитектор (хотя это уже не так важно).
Давайте теперь посмотрим, что должно произойти чтобы запросы на фронтенде и бекенде совпадали:
- Бекенд разработчик не допустил ошибок в реализации API
- Бекенд разработчик правильно понял описание API от архитектора
- Фронтенд разработчик не допустил ошибок в реализации API
- Фронтенд разработчик правильно понял описание 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, но и получить доступ к большому числу инструментов, которые помогут в разработке проекта.
Читайте в нашем блоге:
- Когда стоит выбирать микросервисы
- Параллельные вселенные для вашего CI/CD пайплайна в Octopod
- Антирегрессионное тестирование – минимизируйте затраты
- Property-based тестирование с QuickCheck
Версия на английском языке: https://typeable.io/blog/2021-09-06-api-diff.html