сваггер что это api

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

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

Создание документации вручную — утомительный процесс. Swagger поможет вам упростить эту работу.

Что такое 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

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

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

Для начала создадим класс конфигурации сваггера SwaggerConfig — имя произвольное.

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

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

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

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

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

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

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

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

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

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

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

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

Разметка DTO

Разработчики стараются называть переменные в классе понятными именами, но не всегда это помогает. Вы можете дать человеко-понятное описание самой DTO и ее переменным с помощью аннотации @Schema

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

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

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

Валидация

Подробнее о валидации данных в этой статье.

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

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

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

Источник

От API first на Swagger до Single contract на RAML

Ты наверняка знаешь, что такое API интерфейсы и то, как много от них зависит в твоем проекте. Более того, я так же полагаю, что ты уже знаком с тем, что такое API first подход и знаешь, что Swagger и его Open API являются одними из самых популярных инструментов, помогающих ему следовать.

Но в этой статье я хочу рассказать про подход к реализации API first, концептуально отличающийся от того, что предлагает Swagger и Apiary. Во главе идеи стоит понятие Single contract и возможность его реализации на базе RAML 1.0.

От API first на Swagger до Single contract на RAML

При проектировании современных программных систем часто встает задача согласования и разработки интерфейсов для взаимодействия их компонентов друг с другом. В последнее десятилетие огромную популярность и развитие получили SPA и thick мобильные приложения взаимодействующие с сервером через API интерфейсы. Если раньше разработка интерактивного веб сайта происходила путем поэтапных правок кода серверной стороны для генерации HTML разметки с ее последующей передачей браузеру клиента, то теперь разработка динамических веб приложений сместилась в сторону создания единого API сервиса и параллельной разработки множества приложений (в том числе и SPA) работающих с этим API как с главным источником данных. Такой подход позволяет более удобно разделять задачи, организовывать команды, специализирующиеся только на конкретных технологиях (привлекать более узконаправленных специалистов), организовать параллельную разработку на самых первых этапах, а также позволяет создать единую точку коммуникации — API интерфейс.

Такая единая точка коммуникации требует формального и однозначного определения, этим документом является API спецификация. Для разработки и документирования API спецификаций сегодня применяются различные технологии и языки, например: OAS (Swagger), Apiary и RAML.

Следующие три пункта определяют природу API first подхода:

Single Contract. Контрактные инструменты и библиотеки

Термин Single contract не претендует ни на какое участие в критике за его использование в тексте статьи. Его применение, в данном контексте, является лично моей идеей.

Расширение понятия API first, до более общего Single contract позволяет рассматривать API-спецификацию не только как формальное описание интерфейса взаимодействия между компонентами системы, но и как единый контракт, используемый любым количеством внешних библиотек и инструментов в качестве источника конфигурации. В таком случае, эти инструменты и библиотеки можно воспринимать как клиенты контракта наравне со SPA или мобильными приложениями. Примерами таких клиентов могут быть:

Swagger (OAS) как инструмент описания Single contract

Существующие наиболее популярные на рынке Swagger (OAS) и Apiary (Blueprint) позволяют описывать HTTP API интерфейсы, используя специальные языки: Open API на базе YAML или JSON, Blueprint на базе Markdown, что делает спецификации легко читаемыми. Также существует множество инструментов и библиотек, созданных большим open-source сообществом. Swagger на данный момент широко распространен и, можно сказать, стал де-факто стандартом API first. Многие внешние системы поддерживают импорт Swagger спецификаций, например SoapUI, Readme.io, Apigee и т.д. Кроме того, существующие SaaS Swagger Hub и Apiary позволяют пользователям создавать проекты, загружать или создавать свои спецификации, пользоваться встроенными генераторами документации и mock-серверами, а также публиковать ссылки для доступа к ним извне.

Swagger вместе с его OAS 3.0 выглядят довольно уверенно и его функционала для описания API (особенно простого) хватает в большинстве случаев. Далее приведен список плюсов и минусов Swagger:

Например, реализация «умного» mock api server требует больше информации, чем способен дать документ спецификации, именно поэтому встроенный в Swagger Hub mock API способен только на генерацию фейковых данных на основе типов данных/структур, полученных из документа спецификации. Несомненно, этого мало и такая функциональность mock-сервера может удовлетворить лишь несложный API клиент.

В нашей компании, в ходе разработки одного из проектов (React SPA + API server), потребовался следующий функционал mock-сервера:

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

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

Некоторые примеры сервисов, работающих по схожему принципу:

RAML, annotations, overlays

Стремление найти инструмент, исключающий ранее указанное ограничение OAS, позволяющий рассматривать спецификацию как единый контракт для всех клиентских инструментов, привело нас к знакомству с языком RAML. Про RAML достаточно написано, можно прочитать, например, здесь https://www.infoq.com/articles/power-of-raml. Разработчики RAML попытались заложить в язык поддержку модульности на уровень его концепции. Теперь каждая компания или индивидуальный разработчик может создавать свои или использовать уже готовые публичные словари при проектировании API, переопределять и наследовать уже готовые модели данных. Начиная с версии 1.0 RAML поддерживает 5 различных типов внешних модулей: include, library, extension, trait, overlay, что позволяет применять каждый из них в зависимости от задачи максимально гибко.

Пришло время обсудить главную возможность RAML, которая, по не совсем понятным причинам, не имеет аналогов в OAS и Blueprint — Annotations.

Annotations в RAML — это возможность прикрепления пользовательских метаданных к базовым структурам языка.

Именно эта функция RAML и стала поводом для написания этой статьи.

Сами структуры пользовательских аннотаций должны иметь четкие описания на языке RAML. Для этого используется специальная секция annotationTypes, определения из которой, также можно вынести во внешний модуль. Таким образом, появляется возможность определения специальных параметров внешнего инструмента в виде аннотаций, привязанных базовому определению API RAML. Во избежание захламления базовой спецификации огромным количеством аннотаций для различных внешних инструментов, имеется поддержка возможности их выноса в отдельные файлы — overlays (а можно и в extensions), с классификацией по области применения. Вот что сказано про overlays в документации к RAML (https://github.com/raml-org/raml-spec/blob/master/versions/raml-10/raml-10.md#overlays):

An overlay adds or overrides nodes of a RAML API definition while preserving its behavioral, functional aspects. Certain nodes of a RAML API definition specify the behavior of an API: its resources, methods, parameters, bodies, responses, and so on. These nodes cannot be changed by applying an overlay. In contrast, other nodes, such as descriptions or annotations, address concerns beyond the functional interface, such as the human-oriented descriptive documentation in some language, or implementation or verification information for use in automated tools. These nodes can be changed by applying an overlay.

Overlays are particularly important for separating interface from implementation. Overlays enable separate lifecycles for the behavioral aspects of the API that need to be controlled tightly, such as a contract between the API provider and its consumers, versus those needing little control, such as the human- or implementation-oriented aspects that can evolve at different paces. For example, adding hooks for testing and monitoring tools, appending metadata relevant to a registry of APIs, or providing updated or translated human documentation can be achieved without changing any aspects of the behavioral aspects of the API. These things can be controlled through a rigorous version and change management process.

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

Пример базовой структуры:

В результате появляется возможность реализации единого контракта: вся функциональная, поведенческая и метаинформация хранится и версионируются в одном едином месте, а контрактные инструменты — клиенты контракта, должны иметь поддержку используемых аннотаций в данной спецификации. С другой стороны, именно сами инструменты могут предъявлять собственные требования к аннотациям, которые необходимо “навесить” на спецификацию — это обеспечит более широкий круг возможностей при разработке контрактных инструментов.

Вышеизложенная концепция изображена на рисунке ниже:

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

Возможным и самым очевидными решением будет разработка специального редактора или дополнения для существующего онлайн редактора RAML https://github.com/mulesoft/api-designer. Область редактирования остается неизменной, но появляется возможность создания табов: каждый новый таб является окном для редактирования закрепленного за ним оверлея. При редактировании базовой структуры спецификации в основном окне, меняются также структуры во всех созданных табах, а при обнаружении несовместимости новой структуры с уже существующими аннотациями размещенных в табах-оверлеях появляется предупреждение. Более детальное рассмотрение такого редактора является отдельной темой и заслуживает серьезного обдумывания.

Существующие наработки

В ходе поиска существующих решений, близких к реализации идеи использования аннотаций как средства описания метаинформации, были найдены следующие решения:

Проблемы RAML

Несмотря на функциональность, прогрессивность базовой идеи, внимания со стороны крупных производителей программного обеспечения (cisco, spotify, vmware и т.д.), на сегодняшний день RAML имеет серьезные проблемы, которые могут стать фатальными относительно его успешной судьбы:

Концептуальные разногласия. Первое заключение

We call information that describes available resources types, their behavior, and their relationships the resource model of an API. The resource model can be viewed as the RESTful mapping of the application data model.

В RAML application data model это типы объявленные в блоке types, а resource model of an API — это то, что описывается в блоке resources RAML. Следовательно, необходимо наличие возможности описания этого mapping. Но текущая реализация RAML позволяет сделать такой mapping только 1 к 1, то есть, использовать types “как есть” внутри объявления API ресурсов.

Я считаю это самой главной проблемой языка, решение которой, позволит RAML выйти за рамки API definition language и стать полноценным model definition language: более общим языком (нежели чем OAS или Blueprint) используемым для описания единых контрактов систем, по сути своей, являющихся формальным ядром множества их компонентов.

Выше перечисленное делает RAML слабым игроком, который в данный момент не способен выиграть конкурентную борьбу у Swagger. Возможно, именно поэтому в результате главный разработчик RAML пошел на кардинальные меры https://blogs.mulesoft.com/dev/api-dev/open-api-raml-better-together/

Идея Single contract RAML SaaS

Базируясь на понятии Single contract, отталкиваясь от идеи хостинга API спецификаций Swagger hub на основе OAS, а также полагаясь на возможности RAML объявления метаинформации и разделения базовой спецификации при помощи оверлеев, напрашивается идея альтернативного SaaS решения для хостинга и управления спецификациями на основе языка RAML которое способна превзойти Swagger Hub и Apiary объемом и качеством возможного функционала.

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

Технически каждый таб будет являться абстракцией над RAML overlay содержащим аннотации каждого конкретного плагина. Этим гарантируется совместимость спецификации с любым инструментом поддерживающим RAML 1.0.

Каталог плагинов должен быть открытым для расширения open source сообществом. Также возможна реализация платных плагинов, что может послужить стимулом для разработки новых.

Возможные плагины: API документация с поддержкой большого количества аннотаций для гибкой параметризации ее рендеринга, “умный” mock сервер (из примера выше), скачиваемые библиотеки для валидации запросов или кодогенерации, средства отладки исходящих запросов API для мобильных приложений (caching proxy), нагрузочные тесты с настройкой flow тестирования через аннотации, различные плагины для интеграции с внешними сервисами.

Данная идея сервиса содержит явные преимущества перед существующими сервисами для управления API-спецификациями и ее реализация закладывает начало возможного изменения подхода к имплементации любых внешних систем так или иначе связанных с API.

Второе заключение

Целью этой статьи не является критика Swagger, Apiary или других де-факто стандартных инструментов для разработки API, а скорее рассмотрение концептуального различия c подходом к проектированию спецификаций продвигаемым RAML, попыткой введения понятия Contract first и рассмотрения возможности его реализации на базе RAML. Другой целью явилось желание привлечь к RAML вполне заслуженного внимания разработчиков для дальнейшего возможного развития его сообщества.

Источник

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:

Источник