Swagger — это набор инструментов для разработчиков API от SmartBear Software [1] и бывшая спецификация, на которой основана спецификация OpenAPI . [2]
Проект Swagger API был создан в 2011 году Тони Тэмом, техническим соучредителем сайта-словаря Wordnik . Во время разработки продуктов Wordnik необходимость автоматизации создания документации API и клиентского SDK стала основным источником разочарования. Тэм разработал простое JSON- представление API, опираясь на гибкость протокола HTTP и используя множество функций инструментария, созданного для протокола SOAP . Концепция пользовательского интерфейса была предложена Аюшем Гуптой, который предположил, что интерактивный пользовательский интерфейс принесет пользу конечным пользователям, желающим «попробовать» и разработать API. Рамеш Пидикити руководил реализацией первоначального генератора кода, а дизайнер/разработчик Зик Сикелианос придумал название Swagger. Проект Swagger API был открыт в сентябре 2011 года. Вскоре после выпуска в проект был добавлен ряд новых компонентов, включая автономный валидатор, поддержку Node.js и Ruby on Rails .
В ранние годы Swagger скромную поддержку оказывали небольшие компании и независимые разработчики. HTTP API обычно не имели механизма описания, пригодного для машинного чтения, и Swagger предоставлял простой и понятный способ сделать это. Тони пригласили на встречу с некоторыми лидерами мысли в индустрии API, включая Джона Массера ( ProgrammableWeb ), Марша Гардинера ( Apigee , теперь продукт Google), Марко Палладино ( Kong ) и Кина Лейна (API Evangelist), чтобы обсудить усилия по стандартизации описаний API. Хотя встреча не дала конкретного плана действий, она поставила Swagger на карту как важнейшую инновацию в области API.
Благодаря использованию лицензии Apache 2.0 с открытым исходным кодом ряд продуктов и онлайн-сервисов начали включать Swagger в свои предложения, и этот процесс быстро ускорился после принятия его Apigee, Intuit, Microsoft, IBM и другими, которые начали публично поддерживать проект Swagger.
Вскоре после создания Swagger были представлены альтернативные структуры для описания HTTP API, наиболее популярными из которых стали API Blueprint в апреле 2013 года и RESTful API Modeling Language (RAML) в сентябре 2013 года. Хотя эти конкурирующие продукты имели более сильную финансовую поддержку, чем Swagger, изначально они были сосредоточены на других вариантах использования, нежели Swagger, и по состоянию на середину 2014 года интерес к Swagger рос быстрее, чем к комбинации двух других [источник: Google Trends].
В ноябре 2015 года SmartBear Software , компания, которая поддерживала Swagger, объявила, что она помогает создать новую организацию под спонсорством Linux Foundation , которая называется OpenAPI Initiative. Среди основателей — множество компаний, включая Google , IBM и Microsoft . [3]
1 января 2016 года спецификация Swagger была переименована в спецификацию OpenAPI и перемещена в новый репозиторий программного обеспечения на GitHub . [4] Хотя сама спецификация не была изменена, это переименование означало разделение между форматом описания API и инструментами с открытым исходным кодом.
По данным хостинговых репозиториев Sonatype и npm , по состоянию на июль 2017 года инструменты Swagger загружались более 100 000 раз в день. [ необходима ссылка ]
Использование инструментария Swagger с открытым исходным кодом можно разделить на несколько вариантов использования: разработка, взаимодействие с API и документирование.
При создании API, инструментарий Swagger может использоваться для автоматического создания документа Open API на основе самого кода. Это встраивает описание API в исходный код проекта и неформально называется code-first или разработкой API снизу вверх.
В качестве альтернативы, используя Swagger Codegen, разработчики могут отделить исходный код от документа Open API и генерировать клиентский и серверный код непосредственно из дизайна. Это позволяет отложить аспект кодирования.
Используя проект Swagger Codegen, конечные пользователи генерируют клиентские SDK непосредственно из документа OpenAPI, что снижает потребность в клиентском коде, сгенерированном человеком. По состоянию на август 2017 года проект Swagger Codegen поддерживал более 50 различных языков и форматов для генерации клиентских SDK.
При описании в документе OpenAPI, инструментарий Swagger с открытым исходным кодом может использоваться для прямого взаимодействия с API через пользовательский интерфейс Swagger. Этот проект позволяет подключаться напрямую к живым API через интерактивный пользовательский интерфейс на основе HTML . Запросы могут быть сделаны непосредственно из пользовательского интерфейса и опций, изученных пользователем интерфейса. [5]