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

Вступ

• Створення програмних 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