ћерион Ќетворкс

8 минут

OpenAPI Spec – излюбленный выбор экспертов по разработке API, особенно если главным приоритетом €вл€етс€ безопасность. »нструментарий Swagger в этом отношении кажетс€ хорошим вспомогательным средством. ќднако пытатьс€ совместить эти два пон€ти€ – насто€ща€ задача. ¬ы, наверное, уже запутались?

OpenAPI vs Swagger

Ќе беспокойтесь. Ёта стать€ поможет вам во всем разобратьс€.


OpenAPI: хронологи€ его создани€

OpenAPI

OpenAPI – это всемирно признанна€ проектна€ спецификаци€ RESTful API, разработанна€ под эгидой OpenAPI Initiative. Ћучшие игроки IT-индустрии, такие как Google, Capital One, SmartBear, Microsoft, Apigee и PayPal, вместе запустили этот проект. —ама спецификаци€ также поддерживаетс€ Linux Foundation.

OpenAPI также известен как коммерчески нейтральный и независимый от €зыка интерфейс дл€ RESTful API. ќн широко используетс€ дл€ того, чтобы пользователи и машины могли взаимодействовать без фактического доступа к документации, фрагментам исходного кода или аудита перегрузки сети.

’ронологи€ создани€

  • (2009) – OpenAPI и Swagger по€вились благодар€ “они “эму, специалисту по программному обеспечению. ѕервоначально он запустил спецификацию Swagger с открытым исходным кодом дл€ использовани€ в компании.
  • (2011) – перва€ верси€ пользовательского интерфейса Swagger смогла описать JSON API дл€ Wordnik. ќна может использовать консоль разработчика/документацию компании, интеграцию кода и функции генерации кода.
  • (2012) – по€вилась усовершенствованна€, но все же еще бета, верси€.
  • (2014) – сама€ перва€ формализованна€ и официальна€ верси€ Swagger Spec0 была представлена публике в 2014 году. ќна получила высокую оценку пользователей API.
  • (2015) – SmartBear приобрела Swagger Spec.
  • (2016) – Swagger стал «—пецификацией OpenAPI» и был переведен в другой репозиторий Git.
  • (2017) – входит в OpenAPI Initiative

Ќа сегодн€шний день уже доступна верси€ 3.1.0, котора€ пока считаетс€ лучшей. ƒл€ этой версии важно структурирование и форматирование API. ќна выполн€ет процесс аутентификации и авторизации в соответствии со схемами аутентификации HTTP.

ѕомимо этого, аутентификаци€ и авторизаци€ пользовател€ могут быть выполнены путем отправки ключей API в качестве заголовка или файлов cookie. “акже у вас есть возможность использовать методы обнаружени€ OAuth 2 или OpenID Connect из версии 3.1.0.


Swagger: истори€ и инструментарий

Swagger – это, по своей сути, тип €зыка описани€ интерфейса, разработанный дл€ эффективного определени€ процедур использовани€ RESTful API. ќн использует в своей основе JSON.

Ќабор инструментов Swagger включает в себ€ несколько инструментов с открытым исходным кодом и несколько коммерческих инструментов, которые могут использоватьс€ в течение стандартного жизненного цикла API. √овор€ без преувеличений, набор инструментов Swagger упрощает написание API. ќ его попул€рности можно судить по одному лишь факту – на 2017 год инструменты Swagger загружались более 100 000 раз в день.

¬ инструментарий Swagger вошли такие инструменты как:

  1. SwaggerCore – это набор библиотек Java дл€ подготовки, использовани€ и развертывани€ определений OpenAPI.
  2.  онечные пользователи могут использовать Swagger Editor с целью написани€ или модификации спецификаций OpenAPI на основе YAML через попул€рные веб-браузеры. — ним вы можете улучшить читаемость документации, провести предварительный просмотр от лица конечных пользователей и модифицировать ее, чтобы устранить ошибки и сделать ее более удобной в использовании.
  3. —траницы HTML, JS и CSS в репозитории Swagger UI упрощают процесс написани€ документации.
  4. ≈сли вам необходим хороший инструмент дл€ проектировани€ и документировани€, то правильным выбором будет SwaggerHub. ≈го часто используют специалисты дл€ всех типов проектов OpenAPI.
  5. Swagger Parser позвол€ет анализировать определени€.
  6. Swagger Codegen – это инструмент дл€ создани€ заглушек сервера API, SDK и других документов.
  7. — помощью Swagger Inspector можно проверить процесс создани€ определени€ OpenAPI. Ёто поможет вам улучшить этот процесс благодар€ тщательному тестированию.

Swagger vs OpenAPI: топ-4 отличи€

  • ƒавайте начнем с основ: OpenAPI = —пецификаци€ дл€ правильного определени€ и описани€ RESTful API. Swagger = Ќабор инструментов, используемый дл€ развертывани€ спецификаций API.
  • Swagger допускает комбинацию host+base_path дл€ одного сервера. — другой стороны, OpenAPI позвол€ет добавл€ть несколько URL-адресов серверов и путей поддоменов дл€ того, чтобы упростить вашу жизнь.
  • ¬се инструменты Swagger используют OpenAPI; обратное также должно быть верно.
  • »нструменты Swagger сохранили свои первоначальные названи€, несмотр€ на то, что Swagger изменил название на спецификацию OpenAPI.
OpenAPI vs Swagger

ќбщее вли€ние Swagger и OpenAPI на создателей API и API-отрасль

 огда “они “эм создавал Swagger, он даже предположить не мог, что в будущем изменит представление о безопасности API и API-отрасли в целом. — течением времени OpenAPI Spec и Swagger стали именами нарицательными при упоминании RESTful API.

ѕоскольку OpenAPI €вл€етс€ бесплатным средством с открытым исходным кодом, которое предлагаетс€ пользовател€м API, то у начинающих разработчиков есть возможность научитьс€ большему и показать весь свой потенциал. ” разработчиков-новичков есть множество возможностей дл€ работы и оттачивани€ своих навыков разработки API.

√лавной задачей разработчиков оставалось поддержание стандартов безопасности на каждом этапе разработки API.  оличество взломов API растет с каждым днем.  рупные предпри€ти€, такие как Cisco Systems, Facebook и Shopify, регул€рно сталкиваютс€ с у€звимост€ми API и изо всех сил пытаютс€ укрепить свою систему безопасности. Ќарушение API в Equifax, которое стоило компании судебного иска в размере 700 миллионов долларов, вынудило предпри€ти€ лучше следить за безопасностью »».

»спользование OpenAPI положительно повли€ло на методы разработки API, поскольку позволило команде разработчиков говорить на одном €зыке и, соответственно, легко общатьс€. –азработчикам больше не требуетс€ убирать назначение API из ключевого функционала или исходного кода.

ѕрин€тие предопределенных стандартов безопасности €вл€етс€ вполне осуществимой задачей, поскольку созданный API может взаимодействовать на простом €зыке и не вызывает беспокойства при обнаружении возможных брешей и угроз безопасности.


„то предлагают Swagger и OpenAPI на сегодн€шний день?

OpenAPI, а равно и Swagger, на сегодн€шний день €вл€ютс€ движущей силой API-индустрии. ќин упрощают создание серверной заглушки дл€ API. –азработчики могут создавать библиотеки клиентских API на более, чем 40 €зыках. ќни расшир€ют возможности разработки API и повышают его безопасность за счет:

  • —оздани€ интерактивного API: –азработчики могут использовать OpenAPI дл€ написани€ интерактивной документации. ћало того, он позвол€ет запускать тесты API непосредственно из браузера во врем€ подготовки документа.
  • ѕоддержки инструментов генерации кода: OpenAPI – это великое благословение, поскольку он полезен при создании серверных SDK и клиентских CDK на нескольких €зыках программировани€. ќн хорошо работает с инструментами генерации кода.
  • јудита: OpenAPI Spec хорошо работает совместно с инструментом Contract Audit, который контролирует защиту операций, св€занных с данными API. ‘актически, этот инструмент €вл€етс€ отличным ресурсом дл€ обеспечени€ безопасности высокого уровн€. ѕри совместной работе OpenAPI Spec и Contract Audit вы€вление проблем безопасности в созданном API и их аудит станов€тс€ не такими утомительными. ћожно выполнить аудит API с самого начала и избавить себ€ от аудита огромного количества API в конце разработки.

 уда держит курс Swagger?

OpenAPI – важна€ утилита, и эксперты рынка утверждают, что она имеет хорошие перспективы. ќднако небольша€ часть людей все же считает, что Swagger тер€ет свой лоск после передачи ключевых спецификаций OpenAPI. ”читыва€, что на сегодн€шний день он используетс€ и играет решающую роль во многих задачах, особенно в тестировании API и повышении уровн€ безопасности, они могут ошибатьс€.

»нструменты Swagger позвол€ют нагл€дно увидеть код и протестировать практическую ценность фрагментов кода в режиме реального времени. Ѕлагодар€ пользовательскому интерфейсу Swagger, разработчикам стало еще проще, чем когда-либо, запускать команды и получать всестороннее представление о функциональных возможност€х системы.

ѕоддержание стандартизации в написании API также возможно с помощью Swagger, поскольку он совместно с OpenAPI предлагает всемирно признанный набор стандартов создани€ API.

»нструменты Swagger также могут помочь в написании API с нул€. »спользу€ Swagger Editor, можно тестировать API в режиме реального времени. Ёто позвол€ет пользовател€м провер€ть проектное решение утилиты на соответствие спецификации OAS OpenAPI и узнать текущий визуальный результат. Ћучшее свойство этого инструмента заключаетс€ в том, что его можно использовать из любой точки.

“акже Swagger Inspector €вл€етс€ одним из важнейших инструментов из набора Swagger, поскольку он позвол€ет создавать свои собственные спецификации API. ¬озможно не только создание настраиваемых API, но и передача этих API другим членам команды.

 огда речь идет о безопасности API в »нтернете, то лучшее решение – это Swashbuckle. Ёто реализаци€ Swagger с открытым исходным кодом, позвол€юща€ конечным пользовател€м создавать живую документацию дл€ всех своих API. Ётот инструмент синхронизирует документацию с вашей текущей версией API и сокращает риски безопасности до нул€.


«аключение

ѕоскольку OpenAPI сформировалс€ из Swagger, то тут €вно было где запутатьс€.

ѕерва€ утилита предназначена дл€ описани€ RESTful API. Ёто хороший инструмент с точки зрени€ безопасности, поскольку он сохран€ет спецификацию в машиночитаемой форме. — другой стороны, втора€ утилита – на сегодн€шний день это фаворит разработчиков в случа€х, когда речь идет о коммерчески нейтральном развертывании OpenAPI Spec.

Ќадеюсь, что когда в следующий раз вы услышите эти два пон€ти€, то не запутаетесь и правильно разберетесь в фактах. ќни оба оказывают положительное вли€ние на API-отрасль и способствуют развитию API.


—кидки 50% в Merion Academy

¬ыбрать курс