Спецификация OpenAPI
| Спецификация OpenAPI | |
| Год начался | 2010 |
|---|---|
| Впервые опубликовано | 10 августа 2011 г. |
| Последняя версия | 3.1.0 15 февраля 2021 г. |
| Веб-сайт | опенапис |
Спецификация OpenAPI , ранее известная как Спецификация Swagger , представляет собой языка определения спецификацию машиночитаемого интерфейса для описания, создания, потребления и визуализации веб-сервисов . [1] Ранее являвшийся частью платформы Swagger , в 2015 году он стал отдельным проектом под контролем OpenAPI Initiative, проекта сотрудничества с открытым исходным кодом Linux Foundation . [2]
Документ OpenAPI представляет собой формальное описание API, которое инструменты могут использовать для создания кода, документации, тестовых примеров и многого другого.
История
[ редактировать ]Разработка Swagger началась в начале 2010 года Тони Тэмом, который работал в компании онлайн-словарей Wordnik . [3]
В марте 2015 года SmartBear Software приобрела спецификацию Swagger API с открытым исходным кодом у Reverb Technologies, материнской компании Wordnik. [4]
В ноябре 2015 года SmartBear объявила, что передает спецификацию Swagger в дар новой организации под названием OpenAPI Initiative при спонсорской поддержке Linux Foundation . Среди других компаний-основателей были 3scale , Apigee , Capital One , Google , IBM , Intuit , Microsoft , PayPal и Restlet. [5] [6]
1 января 2016 года спецификация Swagger была переименована в спецификацию OpenAPI (OAS) и перенесена в новый GitHub репозиторий . [7]
В июле 2017 года OpenAPI Initiative выпустила версию 3.0.0 своей спецификации. [8] MuleSoft , основной разработчик альтернативного языка моделирования RESTful API (RAML), присоединился к OAS и открыл исходный код своего инструмента API Modeling Framework, который может генерировать документы OAS на основе входных данных RAML. [9]
В феврале 2021 года инициатива OpenAPI выпустила версию 3.1.0. [10] Основные изменения в спецификации OpenAPI 3.1.0 включают выравнивание словарей схемы JSON, новые элементы верхнего уровня для описания веб-перехватчиков, которые регистрируются и управляются извне, поддержку идентификации лицензий API с использованием стандартного идентификатора SPDX, разрешение описаний наряду с использованием схемы. ссылки и изменение, делающее объект PathItems необязательным для упрощения создания повторно используемых библиотек компонентов. [11] [12] [13]
Даты выпуска
[ редактировать ]| Версия | Дата | Примечания [14] |
|---|---|---|
| 3.1.0 | 2021-02-15 | Выпуск спецификации OpenAPI 3.1.0 |
| 3.0.3 | 2020-02-20 | Выпуск исправления спецификации OpenAPI 3.0.3 |
| 3.0.2 | 2018-10-08 | Выпуск исправления спецификации OpenAPI 3.0.2 |
| 3.0.1 | 2017-12-06 | Выпуск исправления спецификации OpenAPI 3.0.1 |
| 3.0.0 | 2017-07-26 | Выпуск спецификации OpenAPI 3.0.0 |
| 2.0 | 2014-09-08 | Выпуск Swagger 2.0 |
| 1.2 | 2014-03-14 | Первоначальный выпуск официального документа |
| 1.1 | 2012-08-22 | Выпуск Swagger 1.1 |
| 1.0 | 2011-08-10 | Первый выпуск спецификации Swagger |
Использование
[ редактировать ]Приложения, реализованные на основе файлов интерфейса OpenAPI, могут автоматически генерировать документацию по методам, параметрам и моделям данных . Это помогает синхронизировать документацию , клиентские библиотеки и исходный код. [15]
Когда документ OpenAPI используется для создания заглушек исходного кода для серверов, этот процесс называется скаффолдингом .
Отношения с практиками разработки программного обеспечения
[ редактировать ]Парадигма, при которой сначала согласовывается контракт API, а затем программируется бизнес-логика, в отличие от сначала написания кода программы, а затем написания ретроспективного описания ее поведения в качестве контракта, называется разработкой на основе контракта. Поскольку интерфейс определяется до написания любого кода, разработчики последующих версий могут моделировать поведение сервера и сразу же приступить к тестированию. [16] В этом смысле разработка по контракту также является практикой тестирования со сдвигом влево .
Функции
[ редактировать ]Спецификация OpenAPI не зависит от языка. спецификации ресурсов OpenAPI Благодаря декларативной клиенты могут понимать и использовать сервисы, не зная реализации сервера или не имея доступа к серверному коду. [15]
Инструменты, работающие с OpenAPI
[ редактировать ]Инициатива OpenAPI поддерживает список реализаций спецификации версии 3.0. SmartBear по-прежнему маркирует свои инструменты OpenAPI прозвищем Swagger. Платформа пользовательского интерфейса Swagger позволяет как разработчикам, так и неразработчикам взаимодействовать с API в пользовательском интерфейсе песочницы, который дает представление о том, как API реагирует на параметры и параметры. Swagger может обрабатывать как JSON , так и XML . [15]
Swagger Codegen содержит механизм на основе шаблонов для создания документации, клиентов API и заглушек сервера на разных языках путем анализа определения OpenAPI. В июле 2018 года Уильям Ченг, ведущий участник Swagger Codegen, и более 40 других участников Swagger Codegen объединили код в проект под названием OpenAPI Generator в рамках организации OpenAPI Tools. [17] [18]
Ежегодная конференция
[ редактировать ]Инициатива OpenAPI спонсирует ежегодную конференцию по спецификациям API (ASC). Начало этому событию положила Конференция по стратегии и практике API (APIStrat), которая проводилась на протяжении многих лет и стала частью инициативы OpenAPI в 2016 году.
См. также
[ редактировать ]Ссылки
[ редактировать ]- ^ «Новый совместный проект по расширению спецификации Swagger для создания связанных приложений и сервисов» . Архивировано из оригинала 31 октября 2023 года.
- ^ «Устав инициативы OpenAPI» . Инициатива OpenAPI . Проверено 12 ноября 2019 г. .
- ^ «Создатель Swagger присоединяется к SmartBear» . Проверено 6 августа 2019 г.
- ^ «SmartBear берет на себя спонсорство проекта Swagger API с открытым исходным кодом» . СмартБеар . Проверено 25 марта 2015 г.
- ^ "ЧАСТО ЗАДАВАЕМЫЕ ВОПРОСЫ" . Инициатива OpenAPI . Проверено 12 ноября 2019 г. .
- ^ «Новый совместный проект по расширению спецификации Swagger для создания связанных приложений и сервисов» . linuxfoundation.org . Архивировано из оригинала 27 апреля 2016 года . Проверено 22 апреля 2016 г.
- ^ Инициатива OpenAPI. «Спецификация OpenAPI» . Гитхаб . Проверено 12 ноября 2019 г. .
- ^ «OAI объявляет о выпуске спецификации OpenAPI 3.0.0» . OpenAPI . 26 июля 2017 года . Проверено 19 апреля 2018 г.
- ^ Аврам, Авель (6 мая 2017 г.). «Пространство HTTP API консолидируется вокруг OAS» . ИнфоQ . Проверено 14 мая 2017 г.
- ^ «Спецификация OpenAPI 3.1.0 уже доступна» . Linux.com . 26 апреля 2021 г. Проверено 26 апреля 2021 г.
- ^ Шарбоно, Тайлер (7 апреля 2021 г.). «Что нового в OpenAPI 3.1.0?» . Скандинавские API . Проверено 7 апреля 2021 г.
- ^ «Выпущена спецификация OpenAPI 3.1.0» . Инициатива OpenAPI . 18 февраля 2021 г. Проверено 18 февраля 2021 г.
- ^ Стерджен, Фил (16 февраля 2021 г.). «Миграция с OpenAPI 3.0 на 3.1.0» . Инициатива OpenAPI . Проверено 16 февраля 2021 г.
- ^ «Спецификация OpenAPI версии 3.1.0» . Гитхаб . Проверено 7 ноября 2023 г.
- ^ Перейти обратно: а б с "swagger-api/swagger-spec" . Гитхаб . Архивировано из оригинала 4 июня 2016 года . Проверено 1 декабря 2015 г.
- ^ Прейбиш, Саша (2018). Разработка API: практическое руководство для успешного внедрения в бизнесе . [Беркли, Калифорния]: Apress. ISBN 978-1-4842-4140-0 . OCLC 1076234393 .
Имея доступный документ Swagger (или, если уж на то пошло, любой другой машиночитаемый документ), члены команды могут одновременно начать работу над своей частью проекта.
- ^ Хоппе, Йоханнес (2018). «Swagger Codegen теперь является генератором OpenAPI» . Угловое.Шуле . Проверено 6 августа 2019 г.
- ^ «Форк Swagger Codegen: вопросы и ответы» . Генератор OpenAPI . Проверено 6 августа 2019 г.
Библиография
[ редактировать ]- Хаупт, Ф.; Карастоянова Д.; Лейманн, Ф.; Шрот, Б. (2014). Модельно-ориентированный подход к REST-совместимым сервисам . ICWS 2014. Международная конференция IEEE по веб-сервисам 2014 . стр. 129–136. дои : 10.1109/ICWS.2014.30 . ISBN 978-1-4799-5054-6 .
- Паутассо, Чезаре (2021). Красивые API . ЛинПаб. п. 100.
Внешние ссылки
[ редактировать ]- Веб-сайт инициативы OpenAPI (OAI)
- Веб-сайт конференции по спецификациям API (ASC)
- Веб-сайт Сваггера
- Спецификация OpenAPI на GitHub
- Каталог определений OpenAPI
- OpenAPI Editor: редактор и студия Eclipse OpenAPI (OAS) с богатым пользовательским интерфейсом для проектирования, разработки и тестирования OAS3/OpenAPI.
- OpenAPI для EDI Электронный обмен данными
- Пример спецификации клиента/сервера Petstore.