Статья также доступна на украинском (перейти к просмотру).

Оглавление

• Создание программных HTTP интерфейсов – понятие, термины
• Комплексный инструмент автоматизации разработки API Swagger
• Swagger Core
• Swagger Codegen
• Swagger UI
• Swagger Editor
• Выводы

Создание программных интерфейсов (API) и их документирование являются неотъемлемой частью повседневной работы продуктовых IT-компаний. При значительных объемах и недостаточном уровне автоматизации эффективность такой работы значительно снижается, и поэтому лучшим выходом здесь может стать унификация разработки и документирования за счет использования наборов стандартных элементов и операций для конфигураций проектов. Инструмент Swagger является средством, помогающим реализовать указанный подход с наименьшими потерями качества разработки. Рассмотрим более подробно возможности программного инструмента и примеры его применения на практике.

Создание программных HTTP интерфейсов – понятие, термины

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

• Взаимодействие компонентов системы должно соответствовать модели клиент-сервер;
• Недопустимость фиксирования состояний клиента на стороне сервера;
• Наличие механизма кэширования ответов сервера на стороне клиента;
• Наличие унифицированного интерфейса;
• Обязательно использование промежуточных слоев сетевой архитектуры в виде дополнительных серверов или узлов.

Отдельно следует указать на дополнительные требования по унифицированному интерфейсу:

• Все серверные ресурсы должны иметь свой URI и быть отделены от своих представлений, возвращаемых клиенту;
• Возможность управления серверными ресурсами посредством представления;
• Передаваемые сообщения должны иметь в себе метаданные о методах их обработки;
• Клиенты могут изменять свое состояние только из-за действий, определенных с помощью гиперссылок на сервере.

В случае полного соответствия распределенной системы указанным требованиям она получает статус RESTful-системы для реализации которой могут быть использованы такие известные стандарты, как JSON, HTTP, XML и другие.

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

Начиная с 2015 года, на базе проекта Swagger появился инструментарий для реализации формализованной открытой спецификации.OpenAPI Specification, предназначенная для описания, создания и визуализации работы REST-приложений. Средство позволяет работать с такими читабельными форматами представления данных как JSON, YAML, а также XML при необходимости.

Версия OpenAPI 3.0 для описания данных использует восемь стандартных объектов верхнего уровня, а также набор вложенных. Представим основные объекты:

openapi – содержит версию стандарта, задействованную для проекта;

info – содержит вложенные объекты с основными сведениями об API: описание, название, контакты отдела продаж и прочее;

servers – содержит ссылки на серверы для внешнего доступа;

paths – описівает end points-элементы и операции для возможности взаимодействия с сущностями;

components – хранит набор описаний стандартных схем для документации;

tags – содержит метаданные тегов для повышения уровня детализации описания;

security – содержит описания методов безопасности доступных для применения;

externalDocs – сохраняет ссылку на внешнюю документацию.

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

Комплексный инструмент автоматизации разработки API Swagger

Swagger включает в себя несколько отдельных инструментов для работы с API и документацией. Основные из них следующие:

• Swagger Core;
• Swagger Codegen;
• Swagger UI;
• Swagger Editor.

Рассмотрим каждый из них более подробно.

Swagger Core

Это реализация OpenAPI на языке Java, и поэтому необходимо наличие установленного компилятора для этого языка. Swagger Core представляет собой ядро ??системы и позволяет получить документацию на базе созданного кода.

Последовательность подготовительных действий для работы с инструментом может быть следующим:

• Установить дополнительное программное обеспечение – Java, Apache Maven и Jackson;
• Добавить зависимости, необходимые для подключения инструмента к проекту;
• Настроить maven плагин для получения документации в нужном формате (JSON, YAML);
• Добавить конфигурационный файл, в котором указать информацию о проекте – название, версию API и другие.

Первая зависимость:

<dependency>
	<groupId>io.swagger.core.v3</groupId>
	<artifactId>swagger-annotations</artifactId>
	<version>2.1.6</version>
</dependency>

Вторая зависимость:

<dependency>
	<groupId>org.springdoc</groupId>
	<artifactId>springdoc-openapi-ui</artifactId>
	<version>1.5.2</version>
</dependency>

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

@Parameter – используется для представления параметров в операциях OpenAPI;

@ApiResponse – обозначает ответ в рамках операции;

@RequestBody – обозначает тело запроса;

@Operation – описывает операцию для определенного пути;

@Server – определяет серверы для определения OpenAPI или операции;

@Tag – определяет теги;

@Schema – определяет входящие и исходящие данные.

Пример кода с инструкциями:

@Tag(name = "Petya", description = "The Petya API")
public class UserController {}
	@Operation(summary = "Gets all clients", tags = "client")
	@ApiResponses(value = {
        	@ApiResponse(
                	responseCode = "200",
                	description = "Detected call client",
                	content = {
                        	@Content(
                                	mediaType = "application/json",
                                	array = @ArraySchema(schema = @Schema(implementation = ClientApi.class)))
                	})
	})
	@GetMapping("/clients")
	public List get Clients()

Swagger Codegen

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

• Заглушки серверов – server stub для внешних клиентов, обеспечивающих обмен данными с сервером;
• Клиентская библиотека API – SDK для работы с интерфейсом на стороне клиента.

Кроме того, можно получить готовую документацию на основе кода проекта.

Инструмент позволяет получить код, созданный на многих известных языках программирования. В настоящее время поддерживаются следующие языки и технологии:

• Server stub – Ruby, Scala, Python, PHP, Java, C++, C#, Haskell, NodeJS, Rust, Kotlin;
• API clients – Java, Scala, Haskell, C++, C#, Node.js, Bash, Groovy, Kotlin;
• API documentation – Confluence Wiki, HTML.

Для подключения к проекту необходимо добавить следующую зависимость:

<dependency>
	<groupId>io.swagger.codegen.v3</groupId>
	<artifactId>swagger-codegen-maven-plugin</artifactId>
	<version>3.0.24</version>
</dependency>

Управление программой доступно с помощью командной строки сразу же после запуска исполняемого jar-файлу codegen. Основные команды:

help – получение справки по командам;

config-help – справка по конфигурированию;

generate – генерация кода;

list – вывод списка имеющихся генераторов;

validate – проверка спецификации на валидность;

meta – создание новых шаблонов и конфигураций.

Swagger UI

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

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

Код интерфейса программы создает экран, как в известном открытом проекте Petstore (представлен ниже).

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

Ознакомимся с интерфейсом программы на примере демонстрационной версии проекта Petstore. Для доступа к нему достаточно авторизоваться в Swagger UI, что мы делаем с помощью окна, представленного ниже.

После этого разворачиваем конечную точку Pet и нажимаем кнопку Try it out в правом верхнем углу нового экрана (см. скрин).

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

После внесения в код изменений и их подтверждения с помощью кнопки Execute, программа отправляет curl-запрос и получает ответ сервера, который можно просмотреть во вкладке Response (см. скрин ниже).

Таким образом, мы можем изменять код и тестировать наше API.

Естественно, есть и другие инструменты для анализа формализованной OpenAPI спецификации, и инструмент Swagger UI только один из них. Это, например, такие известные средства, как Readme.io, Gelato, Apiary и другие. Каждый из них имеет свои преимущества и недостатки, равно как и Swagger UI.

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

Swagger Editor

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

Как показано ниже на примере того же проекта Petstore, окно программы состоит из двух частей, одна из которых служит для создания и редактирования спецификации API (с левой стороны), а другая содержит средства управления встроенным инструментом визуализации кода Swagger UI, о котором уже шла речь. Это позволяет сразу же после внесения в код изменений протестировать, не закрывая при этом редактор. Кроме того, в редакторе устроена система проверки кода на соответствие требованиям. В случае обнаружения такого несоответствия, соответствующий фрагмент кода выделяется определенным цветом, что позволяет своевременно устранить ошибку.

Выводы

На современном этапе создания документированного API, как известно, используется два основных подхода. Первый – сначала код, затем документирование. Второй – сначала документирование, а затем код. По мнению многих специалистов, второй подход более профессиональный, но затратный. Swagger предоставляет необходимый инструментарий для каждого подхода и поэтому по определению имеет перспективы использования. Его самый большой недостаток – негибкость и ориентированность на типовые схемы. В то же время этот недостаток становится преимуществом в случае проектирования проектов с большим количеством типовых схем. В этом случае выигрыш в эффективности разработки может превзойти имеющиеся недостатки программы.

Подписывайтесь на наш телеграмм-канал https://t.me/freehostua, чтобы быть в курсе новых полезных материалов.

Смотрите наш канал Youtube на https://www.youtube.com/freehostua.

Мы в чем ошиблись, или что-то пропустили?

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

Дата: 15.02.2024 Автор: Александр Ровник #automation#devops#programming

Голосование 1 2 3 4 5