OpenAPI (спецификация)
The OpenAPI Specification (с англ. — «спецификация OpenAPI»; изначально известная как Swagger Specification[1]) — формализованная спецификация и экосистема множества инструментов, предоставляющая интерфейс между front-end системами, кодом библиотек низкого уровня и коммерческими решениями в виде API. Вместе с тем, cпецификация построена таким образом, что не зависит от языков программирования, и удобна в использовании как человеком, так и машиной[2].
Относительно назначения, OpenAPI рассматривается как универсальный интерфейс для пользователей (клиентов) по взаимодействию с сервисами (серверами). Если спроектирована спецификация для некоторого сервиса, то на её основании можно генерировать исходный код для библиотек клиентских приложений, текстовую документацию для пользователей, варианты тестирования и др. Для этих действий имеется большой набор инструментов для различных языков программирования и платформ[3][2].
Изначально разработка спецификации под названием Swagger Specification проводилась с 2010 года компанией SmartBear. В ноябре 2015 года SmartBear объявила, что она работает над созданием новой организации Open API Initiative при спонсорской поддержке Linux Foundation. 1 января 2016 года спецификация была переименована в The OpenAPI Specification, а её развитие ведётся в рамках Open API Initiative.
Описание
[править | править код]OpenAPI представляет собой формализованную спецификацию и полноценный фреймворк для описания, создания, использования и визуализации веб-сервисов REST. Задачей является позволить клиентским системам и документации синхронизировать свои обновления с изменениями на сервере. Это достигается тем, что методы, параметры, модели и другие элементы посредством OpenAPI интегрируются с программным обеспечением сервера и всё время с ним синхронизируются[4].
История
[править | править код]Swagger
[править | править код]Появление спецификации и начало работ над фреймворком обусловлены инициативой компании Wordnik, для внутренних нужд которой компанией SmartBear был разработан Swagger. Проект стартовал в начале 2010 года[4]. В марте 2015 года SmartBear выкупила спецификацию OpenAPI у Reverb Technologies и перевела его развитие в open source[5].
OpenAPI Specification
[править | править код]В ноябре 2015 SmartBear, как компания, поддерживающая работы над Swagger, анонсировала, что она помогает в создании новой организации Open API Initiative под спонсорством Linux Foundation. Членами данной организации стало множество компаний, включая Google, IBM, Microsoft и др.[6][7] SmartBear подарила этой новой группе спецификацию Swagger[8].
Другими технологиями, предоставляющими подобные решения, как и OpenAPI, являются RAML и API Blueprint[9].
В 2016 году Swagger получил награду API Award в категории API Infrastructure[10].
Особенности
[править | править код]Спецификация не зависит от языка программирования, и может быть использована вне протокола HTTP. OpenAPI одновременно применяется для клиента, сервера и соответствующей документации интерфейса, созданного согласно REST[4].
Спецификация декларативна, и поэтому может быть использована клиентами без знаний особенностей серверной реализации. При этом работать с OpenAPI могут как разработчики, так и рядовые пользователи через готовые инструменты и предоставляемые интерфейсы. В качестве формата используется XML и JSON, но в общем случае может быть выбран и другой язык разметки[4] (например, YAML[значимость факта?]).
См. также
[править | править код]Примечания
[править | править код]- ↑ OpenAPI Specification (aka Swagger RESTful API Documentation Specification). Дата обращения: 1 ноября 2016. Архивировано 29 октября 2016 года.
- ↑ 1 2 Swagger, Getting Started. Дата обращения: 1 ноября 2016. Архивировано 13 октября 2016 года.
- ↑ Swagger, Tools and Integrations. Дата обращения: 1 ноября 2016. Архивировано 29 октября 2016 года.
- ↑ 1 2 3 4 OAI/OpenAPI-Specification. Дата обращения: 1 ноября 2016. Архивировано 9 июля 2018 года.
- ↑ SmartBear Assumes Sponsorship of Swagger API Open Source Project. Дата обращения: 1 ноября 2016. Архивировано 24 октября 2016 года.
- ↑ SmartBear, Linux Foundation launch Open API Initiative to Evolve Swagger. Дата обращения: 1 ноября 2016. Архивировано 9 ноября 2016 года.
- ↑ New Collaborative Project to Extend Swagger Specification for Building Connected Applications and Services Архивировано 3 ноября 2016 года.
- ↑ Amazon API Gateway Now Supports Swagger Definition Import. Дата обращения: 1 ноября 2016. Архивировано 3 ноября 2016 года.
- ↑ In 2016, the need for an API meta-language will crystallize. Дата обращения: 1 ноября 2016. Архивировано 10 августа 2016 года.
- ↑ http://apiawards.co/#categories. Дата обращения: 1 ноября 2016. Архивировано 3 ноября 2016 года.
Ссылки
[править | править код]- Сайт Open API Initiative Архивная копия от 22 октября 2016 на Wayback Machine
- Сайт Swagger Архивная копия от 8 ноября 2016 на Wayback Machine
- OpenAPI Specification на GitHub Архивная копия от 20 декабря 2016 на Wayback Machine
- Карта OpenAPI с описанием узлов Архивная копия от 21 апреля 2019 на Wayback Machine
- Карта OpenAPI — только иерархия узлов Архивная копия от 24 марта 2019 на Wayback Machine