Swagger что это такое

Swagger – умная документация вашего RESTful web-API — обзор Junior back-end developer-а для новичков

Предисловие

Команда, в которой я сделала свои первые шаги на поприще написания промышленного кода, занималась разработкой удобного API к функциональности программного продукта на C# (для удобства назовем его, скажем, буквой E), существовавшего уже много лет и зарекомендовавшего себя на рынке с весьма положительной стороны. И здесь вроде бы у юного падавана пока не должно возникать вопросов, однако же представим себе, что ранее вы, скорей всего, конечно, писали собственные web-API, но вряд ли для широкой аудитории, а значит жили по принципу «Сам создал – сам пользуюсь», и если вдруг кого-то бы заинтересовала функциональность вашего API, то вы, наверное, кинули бы ему pdf-файл с подробной инструкцией (по крайней мере я бы сделала именно так). «Где посмотреть функционал апи» — спросила я тимлида ожидая получить ссылку на текстовый документ. «Загляни в Swagger» — ответил он.

Постой, как так получается, что продукт успешно функционирует уже давно, а API вы к нему пишете только сейчас?

Все верно, как такового удобного публичного API у E до недавнего времени не существовало. Фактически вся работа происходила через web-интерфейс, а back-end состоял из множества внутренних микросервисов, с которыми невозможно было интегрироваться извне без четкого понимания внутренней бизнес-логики, уж не говоря о том, что сами они на значительную долю состояли из легаси. Нужно было обратить внимание на клиентов, которые хотят непосредственно напрямую взаимодействовать с сервером, а значит предоставить им красивое и удобное API. Что для этого потребуется? Все, о чем было написано чуть раньше – самим взять и наладить работу со всеми внутренними микросервисами, а также обеспечить удобную и красивую документацию, сделав это красиво, понятно, и самое главное – коммерчески успешно.

Хорошо, так что же есть такое Swagger и в чем его полезность миру?

По сути Swagger – это фреймворк для спецификации RESTful API. Его прелесть заключается в том, что он дает возможность не только интерактивно просматривать спецификацию, но и отправлять запросы – так называемый Swagger UI, вот так это выглядит:

Как мы видим – полное описание методов, включая модели, коды ответов, параметры запроса – в общем, наглядно.

И как это работает?

Отличное руководство для внедрения Swagger в ASP.NET Core
с нуля есть вот в этой этой статье.

Идея в конфигурации отображения с помощью специальных аннотаций у методов API, вот пример:

Swagger Codegen

Если очень хочется, то можно сгенерировать непосредственно клиента или сервер по спецификации API Swagger, для этого нужен генератор кода Swagger-Codegen. Описание из документации, думаю, пояснять не требуется:

This is the Swagger Codegen project, which allows generation of API client libraries (SDK generation), server stubs and documentation automatically given an OpenAPI Spec. Currently, the following languages/frameworks are supported:

Прочая информация, в частности инструкция по использованию, представлена здесь:
Общая информация

Источник

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)

Можно проверять насколько совместимы изменения. Можно настраивать это в дженкинсе

Нет ни какой лишней документации к коде, код отдельно, документация отдельно

Источник

Руководство Swagger UI

Swagger UI предоставляет Фреймворк, который читает спецификацию OpenAPI. и создает веб-страницу с интерактивной документацией. В этом руководстве показано, как интегрировать документ спецификации OpenAPI в интерфейс Swagger.

Концептуальный обзор OpenAPI и Swagger можно посмотреть в разделе Знакомство со спецификациями OpenAPI и Swagger. Пошаговое руководство по созданию документа спецификации OpenAPI смотрим в Обзоре руководства OpenAPI 3.0.

Обзор Swagger UI

Прежде чем мы углубимся в Swagger, нужно прояснить ключевые термины.

Swagger

OpenAPI

Официальное название спецификации OpenAPI. Спецификация OpenAPI предоставляет набор свойств, которые можно использовать для описания REST API. Рабочий, валидный документ можно использовать для создания интерактивной документации, создания клиентских SDK, запуска модульных тестов и многого другого. Подробности спецификации можно изучить на GitHub по адресу https://github.com/OAI/OpenAPI-Specification. В рамках инициативы Open API с Linux Foundation спецификация OpenAPI направлена ​​на то, чтобы быть независимой от производителя (многие компании участвуют в ее разработке).

Swagger Editor

Онлайн-редактор, который проверяет документацию OpenAPI на соответствие правилам спецификации OpenAPI. Редактор Swagger помечает ошибки и дает советы по форматированию.

Swagger UI

Swagger Codegen

Знакомство со Swagger при помощи Petstore

Чтобы лучше понять интерфейс Swagger, давайте рассмотрим пример Swagger Petstore. В примере Petstore сайт генерируется с помощью Swagger UI.

Конечные точки сгруппированы следующим образом:

Авторизация запроса

Прежде чем делать какие-либо запросы, нужна авторизация. Нажимаем кнопку Authorize и заполняем информацию, требуемую в окне «Авторизация», изображенном ниже:

Пример Petstore имеет модель безопасности OAuth 2.0. Код авторизации только для демонстрационных целей. Нет никакой реальной логики авторизации этих запросов, поэтому просто закрываем окно Авторизации.

Создание запроса

Теперь создадим запрос:

Пользовательский интерфейс Swagger отправляет запрос и показывает отправленный curl. Раздел Ответы показывает ответ. (Если выбрать JSON вместо XML в раскрывающемся списке «Response content type», формат ответа будет показан в формате JSON.)

Проверка создания питомца

Примеры сайтов с документаций по Swagger UI

Прежде чем мы перейдем к другому API с этим пособием по Swagger (кроме демонстрации Petstore), посмотрим на другие реализации Swagger:

Некоторые из этих сайтов выглядят одинаково, но другие, такие как The Movie Database API и Zomato, были легко интегрированы в остальную часть их сайта документации.

👨‍💻 Практическое занятие: Создание спецификации OpenAPI в Swagger UI

На этом занятии мы создадим документацию в Swagger UI в спецификации OpenAPI. Если вы используете один из предварительно созданных файлов OpenAPI, вы можете увидеть демонстрацию того, что мы создадим здесь: OpenWeatherMap Swagger UI или Sunrise/sunset Swagger UI).

Для интеграции спецификации OpenAPI в Swagger UI:

Источник

Документирование API с помощью OpenAPI 3 и Swagger

Веб-приложение часто содержит API для взаимодействия с ним. Документирование API позволит клиентам быстрее понять, как использовать ваши сервисы. Если API закрыт от внешнего мира, то все равно стоит уделить время спецификации

Что такое Swagger?

Swagger автоматически генерирует спецификацию вашего API в виде json. А проект Springdoc создаст удобный UI для визуализации. Вы не только сможете просматривать документацию, но и отправлять запросы, и получать ответы.

Также возможно сгенерировать непосредственно клиента или сервер по спецификации API Swagger, для этого нужен генератор кода Swagger-Codegen.

Swagger использует декларативный подход, все как мы любим. Размечаете аннотациями методы, параметры, DTO.

Вы найдете все примеры представленные тут в моем репозитории.

Создание REST API

Чтобы документировать API, для начала напишем его 😄 Вы можете перейти к следующей главе, чтобы не тратить время.

Добавим примитивные контроллеры и одно DTO. Суть нашей системы – программа лояльности пользователей.

Для наших примеров достаточно слоя контроллеров, поэтому я позволю себе вольность опустить серверный и репозиторный слой и добавить бизнес логику в контроллер. В своих проектах старайтесь так не делать.

В качестве DTO у нас будет класс UserDto – это пользователь нашей системы. У него пять полей, из которых 3 обязательны:

UserController отвечает за добавление, обновление и получение пользователей.

PointContoller отвечает за взаимодействие с баллами пользователя. Один метод этого контроллера отвечает за добавление и удаление балов пользователям.

Метод destroy в SecretContoller может удалить всех пользователей.

Настраиваем Swagger

Теперь добавим Swagger в наш проект. Для этого добавьте следующие зависимости в проект.

Swagger автоматически находит список всех контроллеров, определенных в нашем приложении. При нажатии на любой из них будут перечислены допустимые методы HTTP (DELETE, GET, HEAD, OPTIONS, PATCH, POST, PUT).

Для каждого метода доступные следующие данные: статус ответа, тип содержимого и список параметров.

Поэтому после добавления зависимостей, у нас уже есть документация. Чтобы убедиться в этом, переходим по адресу: localhost:8080/swagger-ui.html

Swagger запущенный с дефолтными настройками

Также можно вызвать каждый метод с помощью пользовательского интерфейса. Откроем метод добавления пользователей.

Пока у нас не очень информативная документация. Давайте исправим это.

Эти данные больше для визуальной красоты UI документации.

Добавление авторов

Добавьте разработчиков API, чтобы было понятно, кто в ответе за это безобразие 😄

Разметка контроллеров

Скрыть контроллер

Аннотация скрывает контроллер только из Swagger. Он все также доступен для вызова. Используйте другие методы для защиты вашего API.

Наша документация стала намного понятнее, но давайте добавим описания для каждого метода контроллера.

Разметка методов

Аннотация @Operation описывает возможности методов контроллера. Достаточно определить следующие значения:

Разметка переменных метода

При помощи аннотации Parameter также опишем переменные в методе, который отвечает за управление баллами пользователей.

С помощью параметра required можно задать обязательные поля для запроса. По умолчанию все поля необязательные.

Разметка DTO

Сваггер заполнит переменные, формат которых он понимает: enum, даты. Но если некоторые поля DTO имеют специфичный формат, то помогите разработчикам добавив пример.

Выглядеть это будет так:

Но подождите, зачем мы передаем дату регистрации. Да и уникальный ключ чаще всего будет задаваться сервером. Скроем эти поля из swagger с помощью параметра Schema.AccessMode.READ_ONLY :

Валидация

Давайте посмотрим на изменения спецификации.

И все это нам не стоило ни малейшего дополнительного усилия.

Этих аннотаций вам хватит, чтобы сделать хорошее описание API вашего проекта.

Если нужны более тонкие настройки, то вы без труда сможете разобраться открыв документацию к аннотациям сваггера.

Источник

Swagger: что это такое, и как с ним работать?

Для взаимодействия с любой программой используется API. Он может быть закрытым для внешнего взаимодействия или открытым. В любом случае разработчикам следует уделять внимание его спецификации. Это в том числе нужно для того, чтобы новые члены команды быстрее и проще вовлекались в проект.

Ручное формирование документации — утомительное занятие. Поэтому разработчики придумали Swagger. С его помощью на основе кода можно автоматически сгенерировать спецификации API.

Что такое Swagger?

Swagger — это набор инструментов, которые помогают описывать API. Благодаря ему пользователи и машины лучше понимают возможности REST API без доступа к коду. С помощью Swagger можно быстро создать документацию и отправить ее другим разработчикам или клиентам.

В 2015 году проект Swagger сделали открытым и передали OpenAPI Initiative. Теперь сама спецификация называется OpenAPI. Swagger — инструментарий для работы с OpenAPI, название которого используется в коммерческих и некоммерческих продуктах. Если кто-то называет саму спецификацию Swagger, то это не совсем верно.

Документ спецификации OpenAPI использует YAML, но также может быть написан в формате JSON. Сам по себе он является объектом JSON.

Основные подходы

Swagger предлагает два основных подхода к генерированию документации:

Первый подход проще. Мы добавляем зависимости в проект, конфигурируем настройки и получаем документацию. Сам код из-за этого может стать менее читабельным, документация тоже не будет идеальной. Но задача минимум решена — код задокументирован.

Чтобы пользоваться вторым подходом, нужно знать синтаксис Swagger. Описания можно готовить в формате YAML/JSON. Можно упростить эту задачу, используя Swagger Editor. Конечно, второй подход позволяет сделать документацию более качественной и кастомной для каждого конкретного проекта и его особенностей, к тому же все не так сложно как может показаться, это потребует минимальных дополнительных усилий.

Swagger Core

Это Java-реализация спецификации. Для ее использования потребуется:

Для его внедрения в проект используются две зависимости. Вот примеры:

Другой способ — настроить maven-плагин. Тогда описания при сборке проекта будут генерироваться в файл YAML. Пример:

После настройки конфигурации мы получим аннотации, которые можно использовать для документирования кода.

Swagger Codegen

Это проект для автоматического генерирования клиентских библиотек API, заглушек сервера и документации. Поддерживает большое количество технологий. Посмотреть полный список можно в репозитории Swagger Codegen на GitHub.

В этом же репозитории вы найдёте примеры того, как можно генерировать документацию, используя различные шаблоны.

Плюсы Swagger Codegen:

Чтобы добавить Swagger Codegen в проект, используйте зависимость:

Как и в случае с Swagger Core, можно настроить maven-плагин для генерации клиента или мок-сервера.

Swagger Codegen предоставляет следующие команды:

Swagger UI

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

Swagger Editor

Это онлайн-редактор для изменения и проверки API внутри браузера. Позволяет просматривать документацию в реалтайме. С его помощью можно создать описания, а затем использовать их с полным набором инструментов для генерации документации.

Плюсы Swagger Editor:

Верхний уровень спецификации OpenAPI 3.0 содержит восемь объектов. Внутри этих верхнеуровневых объектов есть много вложенных объектов. Давайте далее последовательно рассмотрим все объекты верхнего уровня.

Первое и самое важное свойство в документации. Объект содержит информацию о спецификации OpenAPI. Пример:

В объекте info содержится основная информация об API: заголовок, описание, версия, ссылки на лицензию, обслуживание, контактные данные. Не все свойства обязательны к заполнению.

Объект содержит базовый путь, который используется в запросах через API. Под базовым путём понимается часть адреса, которая находится перед конечной точкой. Servers можно гибко настраивать, например, указывая несколько адресов для тестирования:

В этом объекте хранятся различные схемы спецификации. Схемы позволяют заметно ускорить процесс составления описаний. Например:

Теперь можно ссылаться на эту схему и при необходимости без проблем дополнять её новыми полями.

Объект для объявления того, какие механизмы безопасности можно использовать в API.

Например, требование безопасности OAuth2 :

В этом объекте можно указать дополнительную информацию. Например:

Онлайн-редактор Swagger позволяет удобно работать над документацией со спецификацией. Он предлагает разделенный интерфейс. Слева вы пишете спецификацию, а справа видите отображение Swagger UI. В него даже можно отправлять запросы, чтобы сразу проверить правильность кода.

Использование Petstore для знакомства

Авторизация

Прежде всего нужно авторизоваться. Для этого нажмите на кнопку Authorize и заполните необходимую информацию.

В примере используется модель авторизации OAuth 2.0. На самом деле, код представлен в демонстрационных целях, никакой реальной логики за авторизацией нет. Так что можно просто закрыть окно.

Создание запроса

Создадим первый запрос к API. Для этого:

Проверка результата

Напоследок выполним ещё один запрос, чтобы убедиться, что питомец создан.

В ответе должно отобразиться имя созданного ранее питомца.

Это пример очень простой документации, которая позволяет быстро проверить работу доступных методов. Вы можете создать такой сайт самостоятельно или встроить интерфейс Swagger на страницу существующего ресурса — например, в справку о работе своего сервиса.

Как выглядят сайты с документацией Swagger UI

Вот ещё несколько примеров реализации Swagger:

Обращает на себя внимание краткость документации, реализованной с помощью Swagger. Это объясняется тем, что сам по себе Swagger UI предназначен для интерактивного взаимодействия. Нет смысла читать пространные описания, когда можно просто выполнять указанные запросы и проверять, какие ответы приходят.

Как встроить Swagger UI в существующий сайт

Чтобы встроить Swagger UI на свой сайт:

Отображение документации можно проверить локально. Если всё в порядке, загрузите папку dist (ее можно переименовать) на сервер и добавьте документацию на существующий сайт.

Заключение

Swagger — удобный инструмент для создания документации API, который помогает разработчикам сэкономить время. Он предлагает несколько решений для интеграции в проект и формирования интерактивной версии документации, с которой будет удобно взаимодействовать другим разработчикам, внешним пользователям, клиентам.

Чтобы разобраться со Swagger дополнительно, посмотрите эти видео.

Например, вот доклад технического писателя из «Яндекса» о том, что такое вообще API и как работать со Swagger. Много времени также уделено практической части — в ней делается простой Swagger, который затем отображается в Swagger UI и в документации.

Ещё одно классное видео — подробное объяснение, как использовать Swagger:

Источник