OpenAPI- это формат описания API для человеком и машин для API HTTP, и он видит повышение внедрения в индустрии программного обеспечения. Поскольку организации работают над опытом API для себя в качестве производителей, и в качестве потребителей растущего числа сторонних API, это ключ к хорошему процессу для работы с файлами OpenAPI.
Дизайн-первый API
Первоначальный дизайн становится эффективным и эффективным подходом к созданию API. В оригинальных API-интерфейсах описание OpenAPI обновляется для описания предлагаемых изменений API. Документация и фиктивные серверы также могут быть произведены на этом этапе, в то время как обратная связь собирается у заинтересованных сторон. Как только изменения будут утверждены и приняты, API реализован.
Работа в подходе первого дизайна означает, что изменения в дизайне API легко достичь на ранней стадии, где необходимо обновить только описание OpenAPI, и код еще не написан. Недостатком является то, что многие организации считают, что формат OpenAPI трудно работать; Часто описание API представляет собой единый файл, и оно может работать до сотен тысяч строк YAML или JSON.
Хотя наличие хорошего редактора с поддержкой OpenAPI действительно помогает, структура самого описания OpenAPI также может иметь большое значение для вашего опыта создания API.
Используйте Openapi $ ref Syntax
Одна из причин, по которой файлы становятся так долго, заключается в том, что формат OpenAPI, по необходимости, является словесной и потому что одни и те же элементы часто повторяются в нескольких местах. Например, микросервис с информационным бюллетенем, вероятно, имеет поле электронной почты и список подписок, которые одинаковы в более чем одной конечной точке.
OpenAPI облегчает это повторение с его синтаксисом $ Ref. Определите поле один раз в разделе компонентов описания OpenAPI, а затем обратитесь к нему с помощью $ ref в любом месте, где оно необходимо.
Вот фрагмент примера микросервиса с информационным бюллетенем:
Использование $ ref не только делает файлы более управляемыми, но и поощряет согласованность, используя те же определения схемы на протяжении всего описания API. Последовательность является ключевым для опыта API, и, таким образом, синтаксис $ ref служит как производителя, так и потребителя, когда он используется.
Синтаксис $ ref может также относиться к контенту в других файлах, что дает пользователям больше способов облегчить работу их файлов OpenAPI.
Отдельные компоненты
С момента OpenAPI 3.1 (выпущен в феврале 2021 года), описание OpenAPI может быть действительным с любым или несколькими путями, объявленными веб -крючками и компонентами. В практическом плане это означает, что если ваш API является чисто веб -крючками или у вас есть один набор компонентов, которые используются несколькими API, вы можете опубликовать эти описания API без необходимости пустых путей: {} объект.
Особенно для архитектур микросервисов общие компоненты, используемые для обеспечения постоянного опыта в разных модулях, являются популярным и полезным шаблоном.
Например, для приложения для покупок, в котором есть отдельные услуги «учетной записи» и «заказов», может иметь смысл разделить компоненты в один файл OpenAPI, и обратиться к ним от отдельных описаний API для отдельных служб. Структура каталогов будет выглядеть примерно так:
├ackscounts.openapi.yaml ├ack. Компоненты.
Если в файле схемы Customer_name в файле Components.openapi.yaml OpenAPI, другие описания API могут обратиться к нему с помощью синтаксиса, как пример ниже:
$ ref: ‘components.openapi.yaml#/components/schemas/customer_name’ 1 $ ref: ‘components.openapi.yaml#/components/schemas/customer_name’
Каждый файл OpenAPI меньше, что делает его более управляемым для редактирования и просмотра изменений. Когда вы будете готовы опубликовать либо учетную запись, либо API заказа, вы можете объединить файл, используя такой инструмент, как вакуум или Redocly CLI, чтобы создать один файл OpenAPI, который можно использовать для передачи в другой инструмент, такой как платформа документации или шлюз API.
Радикальные файловые структуры OpenAPI
Некоторые организации разделили свои файлы OpenAPI более тщательно, удерживая один файл на операцию, а другой для каждого элемента в разделе компонентов. С синтаксисом $ ref, действительно все возможно! На самом радикальном примере рассылки из ранее в конечном итоге выглядит примерно так:
Независимо от того, проектируете ли вы и создаете свою структуру API таким образом, или используете такой инструмент, как Redocly Cli’s Split, для реструктуризации существующего описания API, работа со многими меньшими файлами имеет преимущества:
- Каждый файл достаточно маленький, чтобы легко открыть и просмотреть
- Вы можете просмотреть несколько файлов одновременно, не теряя свое место в длинном файле.
- Предлагаемые изменения гораздо проще в просмотре, потому что вы можете увидеть, какие области затронуты.
Одним из основных недостатков является то, что каждый файл является «просто» YAML, поэтому нет никакой проверки файлов OpenAPI, когда вы работаете над отдельными элементами. В зависимости от вашей команды, это может быть приемлемым компромиссом, и обычные шаги API и управление могут применяться в CI к комплексной версии описания API.
Какая у вас гранулярность Златовласки?
Нет «правильного» ответа на то, как структурировать ваши файлы OpenAPI. Некоторые команды очень довольны одним файлом и видят никаких проблем для решения. Другие полностью привержены очень детальному подходу и не будут рассматривать изменения.
Правильный ответ для вашей команды может лежать где -то между крайностями, но, зная о вариантах и открытых для изменений, вы можете найти подход, который соответствует вашим потребностям и приводит к более эффективному и более счастливому опыту API.
Буми поддерживает будущее бизнеса с интеллектуальной интеграцией и автоматизацией. Как ведущая категория, глобальная компания SaaS, Boomi празднует более 20 000 клиентов и 800 партнеров, которые используют Boomi для подключения своих приложений, данных и людей. Для получения дополнительной информации посетите Boomi.com. Узнайте больше последних из Boomi Trending Stories YouTube.com/thenewstack Tech Moving быстро, не пропустите эпизод. Подпишитесь на наш канал YouTube, чтобы транслировать все наши подкасты, интервью, демонстрации и многое другое. Группа подпишитесь с эскизом. Лорна Митчелл базируется в Йоркшире, Великобритания; Она является технологическим лидером и экспертом по опыту разработчиков, который увлечен API и инструментами разработчиков. Лорна служит в техническом руководящем комитете для спецификации OpenAPI, находится в совете … Подробнее от Лорны Митчелл
