В этой статье хочу рассказать, что такое 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