OpenAPI — это стандартный способ описать ваш API как для человеческой, так и для машинной аудитории. Из описания OpenAPI производители API могут проверить свой API на предмет соответствия, запускать инструменты автоматического тестирования для их API и публиковать мгновенную документацию. Потребители API также могут использовать эти файлы для питания своих собственных интеграций.
Несмотря на то, что сам стандарт OpenAPI не новым, в последние месяцы некоторые обновления от инициативы OpenAPI, включая обновление спецификации OpenAPI и публикацию двух новых стандартов.
Спецификация наложения OpenAPI, выпущенная в октябре, описывает серию редакций, которые применяются к описанию OpenAPI, что облегчает повторить те же обновления в описание. Почти как новая спецификация OpenAPI Arazzo, выпущенная в мае, предоставляет механизм для описания последовательности вызовов API и того, как выполняется процесс, включающий несколько операций API.
OpenAPI обновления
В качестве выпуска патча, версия спецификации 3.1.1, выпущенная в октябре, получила только незначительные обновления. Но как первые обновления с начала 2021 года, эти обновления показывают, что проект жив и здоров. Многие из изменений были также включены в обновление до OpenAPI 3.0, которое сейчас находится в версии 3.0.4.
Большинство изменений в этих патчевых версиях являются улучшениями формулировки в спецификационном документе, разъясняют множество неоднозначных предложений и добавляя примеры. Некоторые разделы были переработаны в пять новых приложений, и был добавлен новый вступительный текст.
Части документа были расширены и повторно рассчитаны для решения общих вопросов или вопросов от сообщества и предоставить более четкое руководство как сообществам инструментов, так и для конечных пользователей. В частности, некоторые из областей, связанных с анализом документов, типами данных и сериализацией, получили пользу от внимания.
Наряду с изменениями в самой спецификации, опубликованные представления схемы JSON также получили некоторые обновления.
Новая спецификация наложения
Спецификация наложения была в проекте в течение некоторого времени и имела официальный релиз в октябре. Оверлей — это документ JSON или YAML, который описывает серию действий для выполнения в документе OpenAPI.
Некоторые хорошие варианты использования для наложения могут быть:
Обновление описания для операции, параметра или тега, чтобы уточнить и иным образом улучшить формулировку перед публикацией документации. Добавление параметров лиц для всех конечных точек в описании OpenAPI. Удаление всех операций, помеченных как устаревшие, или сопоставление некоторых других критериев, добавляя специфические для инструмента расширения, такие как имена отображения для инструмента документации или имена метода и модулей для генератора SDK.
Оверлей может нацелиться на конкретное описание OpenAPI или использоваться против любых/многих описаний OpenAPI. Следующий пример наложения добавляет лицензию в описание OpenAPI:
В то время как «Первый дизайн» считается наилучшей практикой для разработки API, многие проекты используют подход «код» и автоматически создают описание OpenAPI из кода для приложения API. Работа таким образом затрудняет улучшение описания OpenAPI, потому что оно восстанавливается при изменении кода. Наложения позволяют вносить повторяющиеся изменения в регенерированный OpenAPI.
Несколько инструментов API включают готовую поддержку для работы с наложениями. Попробуйте инструменты CLI от Speakeasy или Bump.sh, или посетите репозиторий OpenAPI для получения дополнительных вариантов.
Новая спецификация Arazzo
Как указывалось ранее, спецификация Arazzo была выпущена в мае прошлого года, но в январе этого года был выпущен патч (самое незначительное обновление) для Spec, для версии 1.0.1. Описание Arazzo — это документ JSON или YAML, детализирующий последовательности API -вызовов, объединяя их в более сложные рабочие процессы.
Для наших современных приложений, где операции более вовлечены, чем один вызов API, Arazzo помогает подключить точки, чтобы нарисовать более широкую картину.
В документе Arazzo описывается один или несколько рабочих процессов, каждый из которых содержит ряд шагов. Каждый шаг является вызовом API и может ссылаться на существующий документ OpenAPI для получения подробной информации о вызове. Каждый шаг включает в себя критерии успеха; Следующий шаг выполняется только в случае соблюдения критериев.
Представление более сложных потоков отлично подходит для создания интерактивной документации для прохождения пользователей через шаги, генерируя SDK, которые могут выполнять несколько вызовов API в качестве одной функции, или тестирование реалистичных рабочих процессов API.
Инструмент для Arazzo находится на ранних стадиях, но в репозитории спецификации Arazzo есть несколько замечательных примеров, которые служат хорошей отправной точкой для всех, кто хочет использовать новый формат. Как Spectral, так и Redocly CLI также добавили поддержку Arazzo к своим инструментам для линии, что является большим импульсом для знакомства и использования формата.
У большинства поставщиков инструментов API есть Arazzo на своих дорожных картах, с инструментами для документирования и тестирования рабочих процессов API, так что это тема «один, чтобы посмотреть» для 2025 года.
Что дальше в Openapi?
OpenAPI — это активный проект с большими планами. Следующим в повестке дня для основной спецификации OpenAPI является выпуск 3.2, ожидаемый в ближайшие месяцы. Версия 3.2 будет включать обновления для схемы безопасности, расширенные теги и другие улучшения.
В настоящее время на ранних этапах планирования находится проект OpenAPI 4.0, названный «Moonwalk». Этот проект будет один, чтобы посмотреть.
Спецификации OpenAPI являются открытыми стандартами, и проекты по их разработке также открыты и добро пожаловать как для участников, так и для зрителей. Ознакомьтесь с веб -сайтом проекта, чтобы узнать о репозиториях, открытых встречах и сообществе Slack.
Буми поддерживает будущее бизнеса с интеллектуальной интеграцией и автоматизацией. Как ведущая категория, глобальная компания SaaS, Boomi празднует более 20 000 клиентов и 800 партнеров, которые используют Boomi для подключения своих приложений, данных и людей. Для получения дополнительной информации посетите Boomi.com. Узнайте больше последних из Boomi Trending Stories YouTube.com/thenewstack Tech Moving быстро, не пропустите эпизод. Подпишитесь на наш канал YouTube, чтобы транслировать все наши подкасты, интервью, демонстрации и многое другое. Группа подпишитесь с эскизом. Лорна Митчелл базируется в Йоркшире, Великобритания; Она является технологическим лидером и экспертом по опыту разработчиков, который увлечен API и инструментами разработчиков. Лорна служит в техническом руководящем комитете для спецификации OpenAPI, находится в совете … Подробнее от Лорны Митчелл
