В современном мире разработка программного обеспечения и интеграция различных сервисов становятся всё более сложными задачами. Программистам приходится работать со множеством HTTP API, которые могут отличаться по структуре, способу передачи данных и документированию. В таких условиях становится критически важно иметь унифицированный подход к созданию, использованию и описанию HTTP API, чтобы снизить затраты времени и ресурсов на их поддержку и интеграцию. Ответом на эти запросы является OpenAPI.
Меня зовут Лев Лейман. Я ведущий бэкенд-разработчик в MedTech-компании СберЗдоровье. В этой статье я постараюсь подсветить всё то, что нужно знать об OpenAPI перед началом работы.
Что такое OpenAPI
OpenAPI — это формализованная спецификация и экосистема инструментов, которая предоставляет интерфейс описания HTTP API. OpenAPI не зависит от языков программирования и позволяет генерировать исходный код для библиотек клиентских приложений, текстовую документацию для пользователей, варианты тестирования и другие элементы на основе спроектированной спецификации для некоторого сервиса.
Чтобы понять, что такое OpenAPI и зачем нужен этот стандарт, достаточно рассмотреть простой «бытовой» пример. Так, в метро каждого города есть карта, которая показывает, какие станции есть, и как они связаны между собой. Так вот, OpenAPI делает то же самое для HTTP API, но вместо станций и линий он описывает функции и данные, которыми обмениваются сервисы. Это позволяет получить полное понимание, как всё устроено «под капотом» системы, поэтому упрощает разработку и использование HTTP API.
Примечание: OpenAPI изначально возник как инструмент под названием Swagger, созданный компанией SmartBear Software в 2010 году. В 2015 году проект перешел под управление Linux Foundation и стал называться OpenAPI. Это позволило стандарту развиваться дальше и привлекать больше сообществ и компаний.
Последняя версия OpenAPI на текущий момент — 3.1.0. На официальном сайте заявлено, что она полностью совместима с JSON Schema.
Зачем нужен OpenAPI
OpenAPI помогает решать целый пул задач.
Документация. Когда у вас есть HTTP API, важно объяснить другим разработчикам, как им пользоваться. OpenAPI позволяет создавать документацию автоматически. Это значит, что вы можете легко показать другим людям, какие данные нужно передать вашему приложению, и что оно вернёт в ответ.
Совместимость. Разные приложения часто используют разные языки программирования и технологии. OpenAPI делает так, чтобы все разработчики могли понимать друг друга независимо от того, какой язык программирования они используют. Он описывает API на простом и понятном языке, который читается всеми одинаково.
Автоматизация. С помощью OpenAPI можно генерировать код для работы с вашим API. Например, если вы создаёте API для своего сервиса, другой разработчик может использовать этот документ, чтобы автоматически создать программу, которая будет обращаться к вашему сервису. Это экономит много времени и снижает вероятность ошибок.
Тестирование. OpenAPI также упрощает тестирование вашего HTTP API. Вы можете использовать инструменты, которые проверяют, соответствует ли ваше реальное поведение заявленному в документации. Это помогает убедиться, что всё работает правильно.
Как работает OpenAPI
Спецификация OpenAPI может быть оформлена в двух форматах: YAML и JSON.
YAML — дружественный формат сериализации данных, концептуально близкий к языкам разметки, но ориентированный на удобство ввода-вывода типичных структур данных многих языков программирования.
JSON — текстовый формат обмена данными, основанный на JavaScript.
Оба формата широко используются для хранения структурированных данных, а выбор между YAML и JSON зависит от предпочтений разработчика и потребностей проекта.
Если вам важнее удобство чтения и редактирования, выбирайте YAML. Если же важна простота обработки машиной, лучше выбрать JSON.
Файл спецификации состоит из нескольких основных элементов:
Путь (path) — указывает, куда отправляется запрос. Например, `/users` может означать путь к списку всех пользователей.
Методы HTTP-запросов (methods) — определяют типы запросов, такие как GET (чтение данных), POST (создание новых данных), PUT (обновление данных) и DELETE (удаление данных).
Параметры (parameters) — указывают, какие дополнительные данные должны быть переданы в запросе. Например, параметр `id` может использоваться для идентификации конкретного пользователя.
Ответы (responses) — описывают возможные результаты выполнения запроса. Например, успешный ответ (код 200) или ошибка (код 404 — страница не найдена).
Схемы данных (schemas) — показывают, какую структуру имеют данные, передаваемые в запросах и ответах. Например, схема может описывать, что объект пользователя включает имя, возраст и адрес электронной почты.
Подходы к написанию OpenAPI
Я бы выделил два основных подхода к написанию спецификаций OpenAPI: генерация из кода и написание вручную. Рассмотрим оба метода подробнее.
Генерация из кода
Подход предполагает автоматическое создание спецификации OpenAPI на основе уже имеющегося кода приложения. Обычно такой метод используется, когда у вас уже есть готовое API, и вам нужно задокументировать его с помощью OpenAPI.
Работает следующим образом.
В проект подключается библиотека. В зависимости от языка, на котором пишется проект, используются аннотации, специальные комментарии или другие подобные конструкции. При этом часто используется автокомплит и документация библиотеки (если она вообще есть и описывает хотя бы часть возможностей, помимо того, как сгенерировать файл из простейшего примера).
На довольно простых HTTP API это, вероятнее всего, не будет вызывать проблем. Но когда ответ начнет усложняться или понадобится принимать в теле запроса сложный объект, описание может оказаться проблематичным. Причем причиной может быть как архитектура кода, так и ограничения библиотеки — например, из-за неполной поддержки спецификации.
Преимущества
Вам не нужно вручную описывать каждую деталь API, что ускоряет процесс создания спецификации.
Не надо писать YAML или JSON, что снижает требования к экспертизе.
Поскольку спецификация генерируется непосредственно из кода, она отражает реальную реализацию API, в какой-то степени снижая риск ошибок и несоответствий.
При изменениях в коде можно сразу обновить соответствующую часть спецификации, что упрощает поддержание актуальности документации.
Библиотека может предоставлять просмотр документации на отдельном URL проекта. В некоторых случаях это действительно полезно и удобно. Нюанс в том, что после каждой правки нужно генерировать спецификацию — это требует ресурсов и немного дополнительного времени.
Недостатки
Некоторые аспекты API может быть сложно отразить в спецификации, если они не полностью реализованы в коде.
Качество генерации сильно зависит от используемого инструмента. Не все генераторы поддерживают сложные случаи или специфичные особенности API.
Написание вручную
Метод подразумевает создание спецификации OpenAPI вручную, без привязки к существующему коду. Такой подход чаще всего используется на ранних стадиях разработки, когда еще нет готового API, либо когда требуется высокая степень кастомизации спецификации. Даже для уже существующего API я нахожу такой подход удобным.
Принцип простой.
Создается файл и в удобном формате (напоминаю, что выбор между YAML или JSON) и описывается HTTP API.
Примечание: Поначалу лучше не забывать заглядывать в справочник. С ним, в зависимости от интенсивности и возможностей автодополнения редактора, освоиться в написании спецификаций можно примерно за неделю.
Преимущества
Вы имеете полный контроль над структурой и содержанием спецификации. Можно детально описать все аспекты API, включая нестандартные кейсы.
Gitlab имеет поддержку OpenAPI и отрисовывает его в интерфейсе.
Спецификацию может написать не только разработчик, но и, например, аналитик, который не умеет писать код и может даже не иметь к нему доступа.
Можно заранее продумать архитектуру и логику API, прежде чем приступать к реализации.
Документация может быть рядом с кодом, в том же репозитории.
В коде не нужны дополнительные конструкции и комментарии, обычно занимающие много места (иногда даже больше, чем сам код).
Ручное написание часто приводит к более качественному и информативному документу, так как вы можете добавить подробные описания и примеры.
Может быть разделена на отдельные файлы и позже, при необходимости, собрана в один.
Недостатки
Требует значительных временных затрат, особенно для больших и сложных API, которые, будут сокращаться по мере освоения.
Есть вероятность допустить ошибки или пропустить важные детали, что может привести к несоответствию спецификации и реального поведения API, особенно в уже работающих проектах.
После завершения разработки API необходимо следить за тем, чтобы спецификация оставалась актуальной и соответствовала изменениям в коде.
Какой подход выбрать?
Выбор подхода зависит от конкретных условий вашего проекта.
При подходе Contract First, конечно, проще будет написать вручную, ведь реализация появится позже и генерировать попросту неоткуда.
Если у вас уже есть готовое HTTP API, то генерация из кода будет неплохим решением. Это, возможно, сэкономит время в начале, но позже может вызвать трудности.
На этапе планирования и дизайна API лучше воспользоваться ручным написанием, чтобы тщательно проработать все детали и избежать возможных проблем на стадии реализации.
Из этого можно сделать вывод, что наиболее удобным и перспективным для поддержки вариантом будет написание вручную. А в случае использования генерации кода — едва ли не единственным. Но все проекты разные и решать нужно, исходя из особенностей в конкретной ситуации.
Правила написания хорошей спецификации OpenAPI
Создание спецификации OpenAPI — важный этап в разработке API, поскольку от её качества зависит, насколько удобно и эффективно смогут работать с вашим API другие разработчики. Чтобы спецификация была максимально полезной и удобной, при ее составлении важно следовать некоторым рекомендациям.
Старайтесь избегать сложных формулировок и избыточных деталей. Документация должна быть понятной даже новичкам.
Избегайте общих фраз вроде «возвращает ошибку». Вместо этого четко указывайте, какая конкретно ошибка может возникнуть и при каких условиях.
Включайте примеры запросов и ответов. Они помогают наглядно продемонстрировать, с какими данными работает API. Это особенно полезно для начинающих разработчиков.
Регулярно обновляйте документацию, чтобы она всегда отражала текущие возможности HTTP API. Несоответствие между документацией и реальной работой API может привести к путанице и ошибкам.
Следуйте стандартам оформления документации. Используйте одинаковые термины и структуры для однотипных элементов. Это сделает вашу документацию более последовательной и легкой для восприятия.
Объясняйте контекст использования методов и параметров. Указывайте, зачем нужен тот или иной элемент и как его следует применять.
Добавьте комментарии там, где это необходимо. Иногда одно предложение может существенно прояснить смысл сложного элемента.
Вместо выводов
OpenAPI даёт разработчикам широкие возможности для создания качественных API-интерфейсов. Одновременно с этим, работа со спецификациями упрощает разработку, документирование и тестирование HTTP API, делая их более понятными и удобными для использования.
Безусловно, наряду с преимуществами, работа с OpenAPI несёт и издержки — например, подготовка документации требует времени и определенной экспертизы. Но наличие отработанных методик и широкий стек доступных инструментов вполне нивелируют предъявляемые требования и снижают порог входа.