В проектах разработки создание документации отнимает много времени, и посторонние люди часто не понимают, насколько она важна для поддержания и дальнейшего развития систем. В лучшем случае это становится очевидным, когда команда, отличная от команды разработчиков, пытается осуществлять сопровождение и вносить улучшения — и такой сценарий скорее правило, чем исключение.
Документирование API, или интерфейсов прикладного программирования, еще более важно. API связывают приложения друг с другом, с источниками данных и другими системами. В настоящее время API играют ключевую роль в соединении программного обеспечения практически во всех видах систем. Однако, чтобы иметь возможность использовать эти интерфейсы, необходимо знать об их структуре и функциях. Именно здесь на помощь приходит спецификация OpenAPI Swagger. Это открытый формат описания, который позволяет получить представление о различных возможностях API. Используя Swagger, даже команды, которые не были непосредственно вовлечены в процесс разработки, могут создавать API. Они могут видеть используемые интерфейсы и мгновенно создавать документацию.
Что такое Swagger?
В прошлом описание API было сложной задачей из-за большого количества различных технологий и языков программирования. С тех пор REST стал моделью программирования для разработки API, что стало большим шагом к более упорядоченной системе. Такие сайты, как Google, Amazon и Twitter, используют RESTful API. Ранее интерфейсы описывались с помощью языка описания веб-сервисов WSDL. С чисто технической точки зрения можно описать REST API с помощью WSDL 2.0. Однако разработчики считают это довольно громоздким. Для решения этой проблемы был представлен язык описания веб-приложений (WADL), но из-за своей XML-структуры он так и не был стандартизирован.
Это объясняет, почему Swagger быстро занял место самой популярной технологии для документации API — или, если быть более точным, самой популярной технологии для часто используемых API REST. Swagger был разработан компанией Reverb, но сейчас он нейтрален к поставщикам и доступен по лицензии с открытым исходным кодом в рамках OpenAPI Initiative, проекта Linux Foundation. В рамках этого проекта Swagger был переименован в OpenAPI Specification, но неофициально он по-прежнему носит более броское название Swagger.
В целях защиты вашей конфиденциальности видео не будет загружаться, пока вы не нажмете на него.
В зависимости от области применения, основным элементом Swagger является либо JSON, либо YAML-файл. Пользовательский интерфейс (UI), который обеспечивает простой способ создания документации API, основан на HTML и JavaScript. Проще говоря, Swagger является языково-нейтральным и машиночитаемым. С помощью пользовательского интерфейса разработчики могут не только управлять документацией, но и использовать Swagger для проведения специальных тестов.
Одним из преимуществ Swagger является его всеобъемлющий режим расширения, который поддерживается основной библиотекой, известной как Swagger Core. Пользовательский интерфейс называется Swagger UI, а генератор кода — Swagger Codegen. Существует также редактор Swagger Editor.
Однако главная сила Swagger — как и многих других решений с открытым исходным кодом — заключается в его обширной экосистеме на GitHub. Там есть генераторы кода практически для каждого языка программирования. Swagger документирует каждый интерфейс со всей необходимой информацией.
Файл документации начинается с номера версии спецификации, а затем дается общая информация об API, четко организованная в категории «info». Swagger также разделяет хост, путь и схемы URL и указывает каждую из них. После этого указывается MediaType для всего API. Можно представить себе эту структуру как сложную систему картотеки.
После того как все распределено по категориям, представляется содержание: пути, операторы, параметры и их описания. Типы данных рассматриваются в отдельном разделе. В пользовательском интерфейсе Swagger все может быть отображено как в текстовом, так и в графическом виде. Это особенно полезно при отправке прямых тестовых запросов из браузера. Это сочетание идеальной документации и возможности генерировать прямые запросы API — вот что делает Swagger таким ценным.
Для чего используется Swagger?
При разработке API очень важно иметь хорошо организованную, понятную документацию. Без нее разработчики не смогут использовать интерфейсы. Это особенно актуально для публичных API — они были бы бесполезны для сообщества, если бы у них не было документации.
Swagger в настоящее время является лучшим способом документирования REST API, поскольку он может отображать почти все веб-сервисы и необходимую информацию. Он развивается вместе с системой, и все изменения автоматически документируются. Причина, по которой это работает так хорошо, заключается в том, что Swagger помещает документацию REST API непосредственно в код.
Отправной точкой любой разработки API является либо программный код («Code First»), либо описание интерфейса («Design First»). В подходе Code First программный код является согласованной отправной точкой. Из него Swagger может напрямую вывести документацию, которая не зависит от используемого языка программирования и может быть прочитана как человеком, так и машиной.
Альтернативный подход — Design First. Как упоминалось выше, разработка на стороне клиента и на стороне сервера часто ведется разными командами. При подходе Design First первым шагом является подготовка описания. Затем код генерируется с помощью Swagger. Существуют генераторы для всех распространенных языков программирования, а шаблоны можно настраивать и расширять.
Таким образом, с помощью Swagger процесс генерации согласованного кода API почти полностью автоматизирован. Если в ручном программировании что-то не так, возникнут ошибки компиляции, которые могут быть обнаружены в системе непрерывной интеграции.
Крупные компании, такие как Zalando, следуют принципу API first и полагаются в этом на Swagger. Разработчики платформы для продаж понимают, насколько важно иметь функционирующие интерфейсы, поэтому они решили сосредоточиться на этом. Внутренние API используются между сервисами разных команд, а внешние — например, для получения товаров или оценок.
Swagger — порядок может быть только хорошим!
Преимущества Swagger значительно перевешивают его недостатки — настолько, что Swagger можно считать отличным стандартным приложением для описания интерфейсов RESTful API. Как и многие другие приложения с открытым исходным кодом, Swagger широко распространен и, соответственно, имеет обширную инструментальную поддержку. В его комитет входят такие технологические гиганты, как Microsoft, IBM и Google, что означает, что спецификация OpenAPI имеет значительную поддержку. Существуют и альтернативы, такие как Restful API Modeling Language (RAML), который также основан на YAML и может создавать еще более сложные определения, чем Swagger. Однако создатель RAML (MuleSoft) теперь присоединился к инициативе OpenAPI.
Небольшим недостатком Swagger является читабельность его документации. Это правда, что он предлагает довольно хорошо подготовленный формат, но к нему нужно некоторое время, чтобы привыкнуть. API Blueprint, использующий синтаксис markdown, доказывает, что это можно сделать проще.
Практический пример Swagger
Вы можете загрузить полный пакет Swagger ZIP с сайта Swagger UI. После загрузки пакета вас спросят, хотите ли вы запустить Swagger локально или на сервере.
Примечание: Если вы хотите запустить его локально, вам понадобится MAMP. После распаковки Swagger UI Master будет помещен либо в каталог MAMP, либо на сервер. Затем вы можете просто вызвать URL сервера или локального узла в браузере, и Swagger автоматически откроет и запустит первую документацию API.
Веб-версия Swagger Editor предоставляет еще более простой вариант. Его можно использовать непосредственно в браузере, при этом дополнительным преимуществом является то, что наряду с текстовым редактором отображается графическая версия документации.
swagger: "2.0"
info:
description: "This is an example of Swagger"
version: "1.0.0"
title: "Swagger Example"
termsOfService: "http://swagger.io/terms/"
basePath: "/v2"
tags:
- name: "Example"
description: "Examples of Swagger"
externalDocs:
description: "More information"
url: "http://example.org"
schemes:
- "https"
- "http"
paths:
/Example:
/Example/Contents:
get:
tags:
- "Example"
summary: "Get example elements"
produces:
- "application/json"
parameters: []
responses:
"200":
description: "successful operation"
schema:
type: "object"
additionalProperties:
type: "integer"
format: "int32"
security:
- api_key: []Этот короткий пример Swagger наглядно демонстрирует понятную структуру. Вся информация четко обозначена и может быть понята независимо от языка программирования.
Документацию можно экспортировать непосредственно в файл YAML или сначала преобразовать в формат JSON. Это файл документации, который можно прочитать в пользовательском интерфейсе Swagger. Отображаемое содержимое начинается с путей, интерфейсов и конечных точек. После этого идут описания и параметры, а также ответы и их значения. С помощью пользовательского интерфейса Swagger можно выполнять специальные тесты на конечных точках.
И, конечно, самое лучшее в инструментах с открытым исходным кодом — это то, что их можно попробовать бесплатно. Это касается как пользовательского интерфейса Swagger, так и всех остальных инструментов, так что попробуйте и убедитесь сами, на что способен Swagger!