Что такое open api
Swagger (OpenAPI 3.0)
Всем привет. Это мой первый пост на Хабре и я хочу поделиться с вами своим опытом в исследовании нового для себя фреймворка.
Мне предоставился момент выбрать тему и подготовить презентацию для своей команды. Вдохновившись спикером Евгений Маренковым, я решил выбрать данную тему. В процессе подготовки, я облазил много статей и репозиториев, чтобы компактно и эффективно донести нужную информацию.
Сейчас хочу поделиться ею в надежде, что кому-то она поможет в изучение Swagger (OpenApi 3.0)
Введение
Я на 99% уверен у многих из вас были проблемы с поиском документации для нужного вам контроллера. Многие если и находили ее быстро, но в конечном итоге оказывалось что она работает не так как описано в документации, либо вообще его уже нет.
Сегодня я вам докажу, что есть способы поддерживать документацию в актуальном виде и в этом мне будет помогать Open Source framework от компании SmartBear под названием Swagger, а с 2016 года он получил новое обновление и стал называться OpenAPI Specification.
Также возможно сгенерировать непосредственно клиента или сервер по спецификации API Swagger, для этого понадобится Swagger Codegen.
Основные подходы
Swagger имеет два подхода к написанию документации:
Документация пишется на основании вашего кода.
Данный подход позиционируется как «очень просто». Нам достаточно добавить несколько зависимостей в проект, добавить конфигурацию и уже мы будем иметь нужную документацию, хоть и не настолько описанной какою мы хотели.
Код проекта становиться не очень читабельным от обилия аннотаций и описания в них.
Вся документация будет вписана в нашем коде (все контроллеры и модели превращаются в некий Java Swagger Code)
Подход не советуют использовать, если есть возможности, но его очень просто интегрировать.
Документация пишется отдельно от кода.
Данный подход требует знать синтаксис Swagger Specification.
Документация пишется либо в YAML/JSON файле, либо в редакторе Swagger Editor.
Swagger Tools
Swagger или OpenAPI framework состоит из 4 основных компонентов:
Теперь давайте поговорим о каждом компоненте отдельно.
Swagger Core
Для того что бы использовать Swagger Core во все орудие, требуется:
Apache Maven 3.0.3 или больше
Jackson 2.4.5 или больше
Что бы внедрить его в проект, достаточно добавить две зависимости:
Также можно настроить maven плагин, что бы наша документация при сборке проект генерировалсь в YAML
Дальше нам необходимо добавить конфиг в проект.
Для конфигурации Swagger необходимо добавить два бина. Где нам нужно будет описать название приложения, версию нашего API, так же можно добавить контакт разработчик который отвечает за данные API
После добавление нужных нам зависимостей, у нас появятся новые аннотация с помощью которых можно документировать наш код.
Вот некоторые из них:
Swagger Codegen
В настоящее время поддерживаются следующие языки / фреймворки:
Java (Jersey1.x, Jersey2.x, OkHttp, Retrofit1.x, Retrofit2.x, Feign, RestTemplate, RESTEasy, Vertx, Google API Client Library for Java, Rest-assured)
Scala (akka, http4s, swagger-async-httpclient)
Node.js (ES5, ES6, AngularJS with Google Closure Compiler annotations)
Haskell (http-client, Servant)
C# (.net 2.0, 3.5 or later)
C++ (cpprest, Qt5, Tizen)
Java (MSF4J, Spring, Undertow, JAX-RS: CDI, CXF, Inflector, RestEasy, Play Framework, PKMST)
C# (ASP.NET Core, NancyFx)
C++ (Pistache, Restbed)
Ruby (Sinatra, Rails5)
API documentation generators:
Что бы внедрить его в проект, достаточно добавить зависимость, если используете Swagger:
и если используете OpenApi 3.0, то:
Можно настроить maven плагин, и уже на процессе сборки мы можем сгенерировать нужный для нас клиент либо мок сервиса.
Также все это можно выполнить с помощью командной строки.
Запустив джарник codegen и задав команду help можно увидеть команды, которые предоставляет нам Swagger Codegen:
Для нас самые нужные команды это validate, которая быстро проверять на валидность спецификации и generate, с помощью которой мы можем сгенерировать Client на языке Java
Swagger UI
Вот пример Swagger UI который визуализирует документацию для моего pet-project:
Нажавши на кнопку «Try it out», мы можем выполнить запрос за сервер и получить ответ от него:
Swagger Editor
На верхнем уровне в спецификации OpenAPI 3.0 существует восемь объектов. Внутри этих верхнеуровневых объектов есть много вложенных объектов, но на верхнем уровне есть только следующие объекты:
Для работы над документацией со спецификацией используется онлайн-редактор Swagger Редактор Swagger имеет разделенное представление: слева пишем код спецификации, а справа видим полнофункциональный дисплей Swagger UI. Можно даже отправлять запросы из интерфейса Swagger в этом редакторе.
Редактор Swagger проверит контент в режиме реального времени, и укажет ошибки валидации, во время кодирования документа спецификации. Не стоит беспокоиться об ошибках, если отсутствуют X-метки в коде, над которым идет работа.
Первым и важным свойством для документации это openapi. В объекте указывается версия спецификации OpenAPI. Для Swagger спецификации это свойство будет swagger:
Объект info содержит основную информацию о вашем API,включая заголовок, описание, версию, ссылку на лицензию, ссылку на обслуживания и контактную информацию. Многие из этих свойство являются не обязательными.
Объект components уникален среди других объектов в спецификации OpenAPI. В components хранятся переиспользуемые определения, которые могут появляться в нескольких местах в документе спецификации. В нашем сценарии документации API мы будем хранить детали для объектов parameters и responses в объекте components
Conclusions
Документация стала более понятней для бизнес юзера так и для техническим юзерам (Swagger UI, Open Specifiation)
Можно проверять насколько совместимы изменения. Можно настраивать это в дженкинсе
Нет ни какой лишней документации к коде, код отдельно, документация отдельно
В чем польза формальных спецификаций вроде OpenAPI?
В этой статье хочу рассказать, что такое OpenAPI и зачем он может быть нужен.
Ваши покемоны
Ваше положение: у вас два разработчика. Один разрабатывает бекенд вашего продукта, а другой – фронтенд.
У вас есть идея для нового супер-классного приложения и вы хотите реализовать его как можно быстрее, поэтому вы призываете опытного архитектора чтобы он заранее спроектировал идеальный API, под который можно будет одновременно разрабатывать фронтенд и бекенд.
Архитектор разрабатывает идеальный API, описывает его в одном большом документе и выдает разработчикам.
Каждый разработчик берет документ, описывающий API, внимательно его читает, и реализует описанный API.
Пять раз отмерь, один раз отрежь
В конечном итоге мы хотим получить фронтенд и бекенд, каждый из которых будет реализовывать одни и те же запросы (фронтенд отправлять, а бекенд обрабатывать). В идеале, эти запросы должны еще и соответствовать тому, что описал архитектор (хотя это уже не так важно).
Давайте теперь посмотрим, что должно произойти чтобы запросы на фронтенде и бекенде совпадали:
Если хоть в одном из этих пунктов кто-то допустит ошибку, то весь ваш проект будет падать. И это с предположением, что архитектор не допускает ошибок (спойлер: таких нет).
Нужно отдельно отметить, что большая ноша ложится на человеческое понимание и человеческую коммуникацию технических деталей. Человеческое понимание в целом довольно трудно дебажить и тестировать.
Люди – самое слабое звено
Закономерным в сложившейся ситуации кажется желание минимизировать человеческий фактор в разработке API. Хочется не иметь человеческого фактора с того момента, как архитектор описал API в своем документе. (Вообще, хочется и от ошибок архитектора избавиться, но технологии до такого пока не дошли.)
Очевидно, что чтобы такое сделать, нужно чтобы выхлопом архитектора был не человеко-читаемый документ, а компьютеро-читаемый документ – своего рода формальная спецификация конкретного API. Если у нас будет такое описание API, мы можем как минимум попытаться возложить последующие шаги на автоматизацию.
Для каждого языка программирования при использовании какого-то конкретного фреймворка обычно не так много способов сделать «каноничную» реализацию какого-то HTTP API. Обычно в фреймворках не так много способов сделать запрос с JSON объектом в теле, и не так много способов считать целое число из пути запроса.
OpenAPI
Было бы здорово иметь возможность один раз описать свой HTTP API, и из этого описание получить совпадающие каркасы для реализации бекенда и фронтенда, которые, из-за отсутствия человека в цепочке, будут с большей вероятностью совпадать. (При условии, что генерация этих каркасов реализована без ошибок, но это, на самом деле, более простая задача.)
О, чудо! Такое уже придумали! И называется оно OpenAPI!
OpenAPI позволяет формально описывать HTTP API в виде YAML файлов. Довольно обширный пример можно посмотреть на editor.swagger.io. Там можно смотреть исходный YAML и человеко-читаемую HTML страничку одновременно.
Если изначальную спецификацию архитектор опишет в виде OpenAPI спецификации, то все взаимодействие между бекендом и фронтендом можно будет сгенерировать автоматически, и оно будет гарантированно совпадать. Таким образом мы вообще исключаем из цепочки человеческий фактор!
Больше чем просто кодогенерация
Кодогенерация – это лишь одно из применений OpenAPI. OpenAPI – открытый формат описания HTTP API, не завязанный на какую-то конкретную экосистему. Он позволяет обмениваться точным описанием API между системами, которые в иных условиях требовали бы ручной «синхронизации» API.
Есть большое количество инструментов, работающих на базе OpenAPI спецификаций. Хорошим ресурсом таких проектов является openapi.tools. Там представлены такие проекты как: GUI редакторы спецификаций, генераторы тестовых серверов по спецификациям, поиск уязвимостей по спецификации, и многое другое!
Используя OpenAPI можно не только повысить точность описания своих API, но и получить доступ к большому числу инструментов, которые помогут в разработке проекта.
Знакомство со спецификациями OpenAPI и Swagger
OpenAPI является спецификацией для описания REST API. Можно рассматривать спецификацию OpenAPI как спецификацию DITA. В DITA существуют определенные элементы XML, используемые для определения компонентов справки, а также требуемый порядок и иерархия для этих элементов. Различные инструменты могут читать DITA и создавать веб-сайт документации на основе информации.
В OpenAPI вместо XML существует набор объектов JSON с определенной схемой, которая определяет их наименование, порядок и содержимое. Этот файл JSON (часто выражается в YAML вместо JSON) описывает каждую часть API. Описывая API в стандартном формате, инструменты публикации могут программно анализировать информацию об API и отображать каждый компонент в стилизованном интерактивном виде.
Взгляд на спецификацию OpenAPI
Чтобы лучше понять спецификацию OpenAPI, давайте взглянем на некоторые выдержки из спецификации. Углубимся в каждый элемент в следующих разделах.
Это формат YAML, взят из Swagger PetStore
Вот что значат объекты в этом коде:
Проверка спецификации
При создании спецификации OpenAPI, вместо того, чтобы работать в текстовом редакторе, можно написать свой код в редакторе Swagger. Редактор Swagger динамически проверяет контент, чтобы определить, является ли созданная спецификация валидной.
Если допустить ошибку при написании кода в редакторе Swagger, можно быстро исправить ее, прежде чем продолжить, вместо того, чтобы ждать запуска сборки и устранять ошибки.
YAML зависим от пробелов и двоеточий, устанавливающих синтаксис объекта. Такое пространственно-чувствительное форматирование делает код более понятным для человека. Однако, иногда могут возникнуть сложности с расстановкой правильных интервалов.
Автоматическая генерация файла OpenAPI из аннотаций кода
Вместо того, чтобы кодировать документ в спецификации OpenAPI вручную, также можно автоматически сгенерировать его из аннотаций в программном коде. Этот подход, ориентированный на разработчиков, имеет смысл, если есть большое количество API-интерфейсов или если для технических писателей нецелесообразно создавать эту документацию.
Swagger предлагает множество библиотек, которые можно добавлять в свой программный код для создания документа в спецификации. Эти библиотеки Swagger анализируют аннотации, которые добавляют разработчики, и генерируют документ в спецификации OpenAPI. Эти библиотеки считаются частью проекта Swagger Codegen. Методы аннотации различаются в зависимости от языка программирования. Например, вот справочник по аннотированию кода с помощью Swagger для Scalatra. Для получения дополнительной информации о Codegen см. Сравнение инструментов автоматического генерирования кода API для Swagger по API Evangelist. Дополнительные инструменты и библиотеки см. В разделах «Интеграции и инструменты Swagger» и «Интеграция с открытым исходным кодом».
Хотя этот подход и «автоматизирует» генерацию спецификации, нужно еще понимать, какие аннотации добавить и как их добавить (этот процесс не слишком отличается от комментариев и аннотаций Javadoc). Затем нужно написать контент для каждого из значений аннотации (описывая конечную точку, параметры и т. Д.).
Если идти по этому пути, нужно убедиться, что есть доступ к исходному коду для внесения изменений в аннотации. В противном случае разработчики будут писать документацию (что может и хорошо, но часто приводит к плохим результатам).
Подход: разработка по спецификации
Spec-first development это философия о том, как разрабатывать API более эффективно. Если вы следуете философии «сначала спецификация», вы сначала пишете спецификацию и используете ее в качестве контракта, к которому разработчики пишут код.
Другими словами, разработчики обращаются к спецификации, чтобы увидеть, как должны называться имена параметров, каковы должны быть ответы и так далее. После того, как этот «контракт» или «план» был принят, Стоу говорит, можно поместить аннотации в свой код (при желании), чтобы сгенерировать документ спецификации более автоматизированным способом. Но не стоит кодировать без предварительной спецификации.
Слишком часто команды разработчиков быстро переходят к кодированию конечных точек API, параметров и ответов, без пользовательского тестирования или исследования, соответствует ли API тому, что хотят пользователи. Поскольку управление версиями API-интерфейсов чрезвычайно сложно (необходимо поддерживать каждую новую версию в дальнейшем с полной обратной совместимостью с предыдущими версиями), есть желание избежать подхода «быстрый сбой», который так часто отмечают agile энтузиасты. Нет ничего хуже, чем выпустить новую версию вашего API, которая делает недействительными конечные точки или параметры, используемые в предыдущих выпусках. Постоянное версионирование в API может стать кошмаром документации.
Компания Smartbear, которая делает SwaggerHub (платформу для совместной работы команд над спецификациями API Swagger), говорит, что теперь для команд чаще встречается ручное написание спецификации, а не встраивание аннотаций исходного кода в программный код для автоматической генерации. Подход “spec-first development” в первую очередь помогает работать документации среди большего количества членов команды, нежели только инженеров. Определение спецификации перед кодированием также помогает командам создавать лучшие API.
Даже до создания API спецификация может генерировать ложный ответ, добавляя определения ответа в спецификацию. Мок-сервер генерирует ответ, который выглядит так, как будто он исходит от реального сервера, но это просто предопределенный ответ в коде, и кажется динамичным для пользователя.
Роль технического писателя в спецификации
В большинстве проектов Тома Джонсона разработчики были не очень хорошо знакомы с Swagger или OpenAPI, поэтому он обычно создавал документ спецификации OpenAPI вручную. Кроме того, он часто не имел доступа к исходному коду, и для разработчиков английский язык был не родным. Документация была для них сложным делом.
Возможно, и нам будут попадаться инженеры, не знакомые с Swagger или OpenAPI, но заинтересованные в использовании их в качестве подхода к документации API (подход, основанный на схемах, соответствует инженерному мышлению). Таким образом, нам, вероятно, придется взять на себя инициативу, чтобы направлять инженеров к необходимой информации, подходу и другим деталям, которые соответствуют лучшим практикам для создания спецификации.
В этом отношении технические писатели играют ключевую роль в сотрудничестве с командой в разработке спецификации API. Если придерживаться философии разработки, основанной на спецификациях, эта роль (техписателя) может помочь сформировать API до его кодирования и блокировки. Это означает, что может быть возможность влиять на имена конечных точек, консистенцию и шаблоны, простоту и другие факторы, которые влияют на разработку API (на которые, обычно, не влияют технические писатели).
Визуализация спецификации OpenAPI с помощью Swagger UI
После того, как получился действующий документ по спецификации OpenAPI, описывающий API, можно “скормить” эту спецификацию различным инструментам, чтобы проанализировать ее и сгенерировать интерактивную документацию, аналогичную примеру Petstore.
Наиболее распространенным инструментом, используемым для анализа спецификации OpenAPI, является Swagger UI. (Помните, что «Swagger» относится к инструментам API, тогда как «OpenAPI» относится к независимой от поставщика спецификации, не зависящей от инструмента.) После загрузки пользовательского интерфейса Swagger его довольно легко настроить с помощью собственного файла спецификации. Руководство по настройке Swagger UI есть в этом разделе.
Код пользовательского интерфейса Swagger генерирует экран, который выглядит следующим образом:
На изображении видно, как Swagger отображает спецификацию Open API
Можно ознакомиться с примером интеграции Swagger UI с примером API сервиса погоды, использованным в качестве примера курса.
Некоторые дизайнеры критикуют выпадающие списки Swagger UI как устаревшие. В то же время разработчики считают одностраничную модель привлекательной и способной уменьшать или увеличивать детали. Объединяя все конечные точки на одной странице в одном представлении, пользователи могут сразу увидеть весь API. Такое отображение дает пользователям представление в целом, что помогает уменьшить сложность и позволяет им начать. Во многих отношениях отображение Swagger UI является кратким справочным руководством по API.
👨💻 Практическое занятие: Исследуем API PetStore в Swagger UI
Давайте познакомимся с пользовательским интерфейсом Swagger, используя Petstore.
Окно авторизации в Swagger UI
Разворачиваем конечную точку Pet
Выполнение примера Petstore запроса
Swagger UI отправляет запрос и показывает отправленный curl. В примере был отправлен curl:
В разделе “Ответы” Swagger UI выдает ответ сервера. По умолчанию ответ возвращает XML:
Если выбрать в выпадающем списке “Response content type” JSON, то в ответе вернется JSON вместо XML.
Другие инструменты визуализации
Помимо Swagger UI есть и другие инструменты, которые могут анализировать нашу документацию OpenAPI. Вот список из нескольких инструментов: Restlet Studio, Apiary, Apigee, Lucybot, Gelato, Readme.io, swagger2postman, отзывчивую тему swagger-ui, Postman Run Buttons и многое другое.
Кастомизация Swagger UI
Однако, помимо этих простых модификаций, потребуется немного мастерства веб-разработчика, чтобы существенно изменить отображение пользовательского интерфейса Swagger. Возможно, понадобятся навыки веб-разработки.
Недостатки OpenAPI и Swagger UI
Несмотря на то, что Swagger обладает интерактивными возможностями апеллировать к желаниям пользователей «дай мне попробовать», у Swagger и OpenAPI есть некоторые недостатки:
Некоторые утешения
Несмотря на недостатки спецификации OpenAPI, он все же настоятельно рекомендуется ее для описания API. OpenAPI быстро становится средством для все большего и большего количества инструментов (от кнопки запуска Postman для почти каждой платформы API), для быстрого получения информации о нашем API и для превращения ее в доступную и интерактивную документацию. С помощью своей спецификации OpenAPI можно портировать свой API на многие платформы и системы, а также автоматически настраивать модульное тестирование и создание прототипов.
Swagger UI обеспечивает определенно хорошую визуальную форму для API. Можно легко увидеть все конечные точки и их параметры (например, краткий справочник). Основываясь на этой структуре, можно помочь пользователям понять основы вашего API.
Кроме того, изучение спецификации OpenAPI и описание своего API с его объектами и свойствами поможет расширить свой собственный словарь API. Например, станет понятно, что существует четыре основных типа параметров: параметры «пути», параметры «заголовка», параметры «запроса» и параметры «тела запроса». Типы данных параметров в REST: «Boolean», «number», «integer» или «string». В ответах содержатся «objects», содержащие «strings» или «arrays».
Короче говоря, реализация спецификации даст еще и представление о терминологии API, которая, в свою очередь, поможет описать различные компоненты своего API достоверными способами.
OpenAPI может не подходить для каждого API, но если API имеет довольно простые параметры, без большого количества взаимозависимостей между конечными точками, и если нет проблем исследовать API с данными пользователя, OpenAPI и Swagger UI могут быть мощным дополнением к документации. Можно давать пользователям возможность опробовать запросы и ответы.
С таким интерактивным элементом документация становится больше, чем просто информация. С помощью OpenAPI и Swagger UI мы создаем пространство для пользователей, которые одновременно могут читать нашу документацию и экспериментировать с нашим API. Эта комбинация имеет тенденцию предоставлять мощный опыт обучения для пользователей.
Ресурсы для дальнейшего чтения
Вот источники для получения дополнительной информации об OpenAPI и Swagger:
Оpen API: что это такое, как работает, и чем полезно бизнесу, финтех-стартапам и разработчикам
Что такое Open API
Опытные путешественники знают — в разных частях света розетки разные. Привычная для нас вилка не подойдёт к классической американской розетке. Вы хотите зарядить смартфон, и подобрали правильную вилку. Но это даже не полдела, а 1/3.
Разъём на выходе тоже должен совпадать с зарядным “гнездом” вашего телефона: быть плоским, круглым, mini-USB… Должна подходить и сама зарядка — выдавать нужное для мобильника напряжение. Смартфон сгорит, если пытаться зарядить его через преобразователь для чайника.
Понижающий преобразователь делает возможной зарядку смартфона, а одинаковые разъёмы обеспечивают взаимозаменяемость зарядок.
Это общий принцип работы протокола Open API (Application Programming Interface, открытый программный интерфейс приложения) Есть некая ценность, которой делится её автор (в нашем случае это электричество и условная розетка или электростанция). Есть пользователь, который посылает запрос и получает на него ответ (в нашем примере это смартфон). И есть промежуточное звено, которое делает возможным этот диалог на техническом языке (у нас — зарядка с определёнными разъёмами и преобразователь).
В компьютерном мире Open API — это “расшаривание” интерфейса и возможностей какого-либо продукта для сторонних разработчиков, партнёров, других игроков экосистемы. Они встраивают API в свои сервисы/приложения, делая их удобнее и функциональнее. Благодаря API мы с вами можем логиниться на сторонних сайтах через Facebook, вызывать такси по своей геолокации, платить парой кликов в интернет-магазинах. Сервисы интегрируются друг в друга и делают нашу жизнь удобнее.
API есть и в банках
Одна из важных областей использования технологии Open API — банковская. С её помощью банки и любые другие финансовые организации могут обмениваться данными (например, показывать на сайтах курсы валют, учитывая изменения в реальном времени) и предоставлять внешним площадкам готовые сервисы (например, для перевода денег между пользователями соцсетей).
В ЕС открытие банками Open API — требование “Второй платёжной директивы” (PSD2). К сентябрю 2019 года все финансовые учреждения Европы (не только банки) должны открыть свои API для сторонних разработчиков. Уже сделали это 23% игроков, ещё 51% планируют открыть интерфейсы приложений в течение года.
В Беларуси лёд также тронулся”. Профильные ведомства разрабатывают “”Дорожную карту разработки стандартов открытых банковских API” — она должна быть готова к 1 января 2020 года. Регулятор смотрит в этом направлении, но пока не делает его обязательным условием работы. Но самые прогрессивные банки и другие финансовые организации уже открывают API своих инструментов и сервисов.
Кому удобно, чтобы API банков были открытыми
Всем! В открытых интерфейсах банковских сервисов заинтересованы все: сами банки, их партнёры, финтех-стартапы, актуальные и потенциальные клиенты. Но не все финансовые учреждения открывают свои API. По разным причинам: одни банки не могут обеспечить сохранность персональных данных и защиту от мошенничества на сторонних площадках, другие — боятся конкуренции, их бизнес-модель не подразумевает взаимовыгодного партнёрства с третьими игроками.
Это их выбор, но по этому поводу ещё Iron Maiden пели: “Be quick or be dead”. Парадигма финансовых отношений медленно, но верно меняется во всём мире. Из консервативных держателей капитала банки превращаются в гибкие платформы для мгновенных платежей, переводов, инвестирования, страхования и пр. А те, которые не превращаются, уступают своё место на рынке более динамичным банкам и финтех-стартапам.
Чем Open API Альфа-Банка полезен бизнесу и его клиентам
28 июня Альфа-Банк открывает API для платежей в белорусских рублях. Теперь работать с инструментами банка станет ещё проще.
Юридические лица и ИП смогут…
Разработчики и финтех-стартапы смогут…