Swagger. Що це таке та як з ним працювати?

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

Зміст

Створення програмних інтерфейсів (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;
• Editor Swagger.

Розглянемо кожен із них докладніше.

Swagger Core

Це реалізація OpenAPI на мові Java, і тому потрібна наявність встановленого компілятора для цієї мови. Swagger Core є ядром системи і дозволяє отримати документацію на базі створеного коду.

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

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

io.swagger.core.v3
swagger-annotations
2.1.6

org.springdoc
springdoc-openapi-ui
1.5.2

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

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

@ApiResponse - Позначає відповідь в рамках операції;

@RequestBody - Позначає тіло запиту;

@Operation - Описує операцію для певного шляху;

@Server - Визначає сервери для визначення OpenAPI або операції;

@Tag - Визначає теги;

@Schema – визначає вхідні та вихідні дані.

Приклад коду з інструкціями:

@Tag(name = "Petya", опис = "The Petya API") Public class UserController <> @Operation(summary = "Gets all clients", tags = "client") "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.

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

io.swagger.codegen.v3
swagger-codegen-maven-plugin
3.0.24

Керування програмою доступне за допомогою командного рядка відразу після запуску виконуваного 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, щоб бути в курсі нових корисних матеріалів.

Ми в чому помилилися чи щось пропустили?

Напишіть про це у коментарях, ми із задоволенням відповімо та обговорюємо Ваші зауваження та пропозиції.

Swagger

Swagger - це набір інструментів, який дозволяє автоматично описувати API на основі коду. API — інтерфейс для зв'язку між різними програмними продуктами, і кожен проект має свій. Документація, автоматично створена через Swagger, полегшує розуміння API для комп'ютерів та людей.

Освойте професію
"Fullstack-розробник на Python"

На основі коду або набору правил Swagger автоматично генерує документацію у форматі JSON-файлу. Її можна вбудувати на сторінку сайту або додаток, щоб користувачі могли інтерактивно знайомитися з документацією, можна відправляти клієнтам — згенерувати такий опис набагато швидше, ніж написати з нуля.

Безкоштовний профорієнтаційний проект

Пройдіть тест та визначте ваш напрямок у IT. Вигравайте призи, отримуйте подарунки та особистий план розвитку через безкоштовні гайди та кар'єрну консультацію.

Swagger іноді називають фреймворком. Фреймворк - набір інструментів та правил, яким по суті є Swagger. Частина інструментів доступна безкоштовно і має відкритий вихідний код, ще частина платна і призначена для компаній.

Назва читається як "Сваггер". Альтернативна назва – OpenAPI.Так називається специфікація, за якою працює Swagger, але іноді назва застосовують при описі продукту.

• Розробники, які хочуть швидко задокументувати проект API і не можуть витрачати час на те, щоб писати документацію з нуля.
• Розробники, які збираються впровадити API стороннього програмного продукту, - вони користуються документацією, зокрема створеною в Swagger.
• Тестувальники. Цей інструмент допомагає їм створювати документацію до API, проводити тестування та автоматизувати процес. Swagger полегшує роботу тестувальників, надаючи формат документації, що легко читається, і готові шаблони.
• Технічні письменники під час створення документації для проектів — як основний чи допоміжний інструмент.

Для чого потрібний Swagger

Документація API. Основне призначення Swagger – автоматично генерувати документацію, зрозумілу для людей та для машин. Відповідно, найчастіше він застосовується, щоб швидко та легко документувати код API. Зазвичай використовується у зв'язці з архітектурою RESTful API.

Розробка API. Swagger використовується, коли, наприклад, розробнику потрібно звіритися з документацією при доопрацюванні продукту, або хоче згенерувати її з коду. Іноді потрібний зворотний процес - генерація коду на основі документації, можлива завдяки компоненту Swagger Codegen. Ми поговоримо про нього нижче.

Взаємодія з API. Можливість створення коду використовується при взаємодії з API інших проектів. Swagger Codegen може генерувати код для кінцевого клієнта, який працюватиме з API, - це зручно, коли стоїть завдання заощадити час.

Я займаюся мобільною розробкою більше 10 років і не уявляю свого життя без Swagger. Є 2 речі, які я особливо люблю у цьому інструменті.

Прискорення розробки. У крос-функціональних командах, що працюють по скраму, важливо швидко реалізовувати фічі за один спринт. Напевно, ви чули такі фрази, як «я чекаю, поки бекенд зробить, і тоді я приступлю». Ми не маємо часу чекати і працювати з такими процесами. Тут на допомогу приходить Swagger: він дозволяє публікувати контракт API, що дає можливість усім розробникам – бекенд, фронтенд та мобільним – працювати паралельно. Спроектували API на початку спринту і одразу всі почали працювати паралельно. Це виключає затримки, пов'язані з очікуванням на завершення бекенд-розробки.

Друга моя улюблена перевага Swagger – це документація. Що може зіпсувати ваш день сильніше ніж відсутність документації у API виклику, якому більше 5 років? Риторичне питання. Але, друзі, зізнаємося чесно, ми не любимо писати документацію. Тому будь-який інструмент, який робить це за нас, — це просто золото. Swagger автоматично створює інтерактивну документацію API. Це дуже спрощує розуміння та використання API для всіх членів команди, включаючи QA, та зовнішніх розробників.

Два способи створення документації

На основі коду. Інструмент читає код API і на його основі генерує документацію. Такий спосіб вважається більш простим, тому що від розробника не потрібно знати специфікацію та писати щось, крім самого коду. Але його рекомендують застосовувати лише тоді, коли документація потрібна терміново, тому що другий спосіб дозволяє створювати більш докладні та зрозумілі описи.

За підсумками специфікації. Другий спосіб – використовувати специфікацію Swagger, яка називається OpenAPI. Він складніший, тому що необхідно знати мову формальних правил — нею потрібно описати сутність коду, щоб інструмент зрозумів написане та згенерував документ. Але цей підхід правильніший, тому що така документація більш зрозуміла і людиночитана.Писати необхідно за допомогою форматів JSON або YAML або у спеціальному редакторі Swagger Editor – про нього ми докладніше розповімо нижче.

Стати Java-розробником
та створюйте складні сервіси
затребуваною мовою

Що таке специфікація Swagger

Swagger працює на основі специфікації OpenAPI 3.0. Раніше вона також називалася Swagger, але її перейменували в 2015 році, коли проект передали іншій команді розробників.

Специфікація — набір правил, які описують, як має виглядати та працювати та чи інша технологія. Це теоретичний каркас для майбутнього програмного проекту. На його основі пишеться код, реалізація, яка працює за описаною у специфікації логікою. Відповідно, OpenAPI – це набір правил та стандартів для опису API.

Робота відбувається так: спеціаліст описує код за допомогою формальних текстових правил. Swagger «розуміє» написане і на його основі створює людину зрозумілу інтерактивну документацію.

Як влаштовано специфікацію

У специфікації є основні сутності, кожна з яких включає більш дрібні. З їхньою допомогою відбувається опис документації. Синтаксис приблизно такий:

Об'єкт може являти собою, наприклад, ім'я користувача, назву модуля, посилання або щось інше. Основних об'єктів вісім, інші вкладені у них:

• openapi. Його значення - версія OpenAPI, яка використовується у проекті;
• info. Включає вкладені об'єкти, які містять основну інформацію про API: назву, опис, ліцензію, контакти розробників і т.д.;
• серверів. Включає посилання, що ведуть до серверів, — базові шляхи для доступу ззовні без урахування кінцевих точок;
• paths. Описує кінцеві точки, або ендпоінти (end points) - кінець шляху до тієї чи іншої сутності. Для кожного ендпоінта прописуються запити GET, POST, DELETE та PUT - операції для взаємодії з сутністю;
• компонентів. У ньому зберігаються схеми, які можуть використовуватись у різних місцях документації.Наприклад, можна створити схему «Користувач» з полями «Ім'я», «Адреса» та іншими. Після опису в components схему можна використовувати далі в коді документації;
• tags. Зберігає метадані тегів: заголовок, опис тощо. Допомагає докладніше описувати те, що відбувається;
• security. Описує методи забезпечення безпеки, які можна використовувати з API;
• externalDocs. Містить посилання на зовнішню документацію, як правило, з додатковою інформацією. Наприклад, це може бути документація якогось іншого інструмента, який використовується в коді.

openapi: 3.0.0 info: title: Task Management API description: API для керування завданнями.version: 1.0.0 servers: - url: http://localhost:8080/api description: Локальний сервер paths: /tasks: get: summary: Отримати список усіх завдань responses: '200': description: Список завдань успішно отриманий content: application/json: schema: type: array items: $ref: '#/components/schemas/Task' post: summary: Створити нове завдання requestBody: description: Нове завдання, яке потрібно створити required: true content: application/json: schema : $ref: '#/components/schemas/NewTask' responses: '201': description: Завдання успішно створене content: application/json: schema: $ref: '#/components/schemas/Task' /tasks/: get: summary: Отримати завдання за ID parameters: - name: taskId in: path required: true description: ID задачі schema: type: string responses: '200': description: Завдання успішно отримано content: application/json: schema: $ref: '#/components/schemas/Task' '404': description: Завдання не знайдено put: summary: Оновити завдання по ID parameters: - name: task задачі schema: type: string requestBody: description: Оновлені дані завдання required: true content: application/json: schema: $ref: '#/components/schemas/NewTask' responses: '200': description: Завдання успішно оновлено content: : /json: schema: $ref: '#/components/schemas/Task' '404': description: Завдання не знайдено delete: summary: Видалити задачу за ID parameters: - name: taskId in: path required: true description: ID задачі schema: type: string responses: '204': description: Завдання успішно видалено '404': description: Завдання не знайдено components: schemas: Task: type: object properties: id: type: string description: Унікальний ідентифікатор задачі title: type: string description: Назва задачі description: type: string description: Опис задачі status: type: string description: Статус задачі enum: [pending, in progress, completed] NewTask: type: object properties: title: type: string description: Назва задачі example: Купити молоко description: type:string description: Опис завдання example: Не забути купити молоко після роботи status: type: string description: Заголовок завдання enum: [pending, in progress, completed] example: pending

Цей приклад описує API, що дозволяє:

• Отримати список всіх завдань (GET/tasks)
• Створити нове завдання (POST/tasks)
• Отримати завдання ID ( GET /tasks/ )
• Оновити завдання за ID (PUT /tasks/)
• Видалити завдання за ID ( DELETE /tasks/ )

4 компоненти Swagger

Swagger можна розділити на чотири основні компоненти. Є й інші, які відносяться до комерційної версії, але про них говорять рідше і використовують не так часто.

Swagger Core. Це ядро ​​Swagger – програмна реалізація специфікації OpenAPI 3.0. Вище ми говорили, що на основі специфікації пишеться код, який реалізує описану в ній логіку. У випадку зі Swagger це і є Core.

Swagger Core написаний мовою Java, тому для його коректної роботи знадобиться Java не старше версії 8.0. Також потрібні будуть фреймворк Apache Maven 3.0.3 або новіші та JSON-процесор Jackson 2.4.5 або новіші.

Після встановлення проект Swagger Core дозволить автоматично генерувати документацію на основі коду при складанні проекту. Правила генерації описуються за допомогою спеціальних команд - анотацій: вони розміщуються в коді і показують, що саме є та чи інша його частина. Це один із мінусів способу генерації на основі коду - він стає дуже масивним і громіздким через велику кількість анотацій.

Стати веб-розробником і знайти стабільну роботу на віддаленні

Swagger UI. UI розшифровується як user interface, графічний інтерфейс. Цей компонент робить роботу зі Swagger наочнішим і зрозумілішим: він візуалізує документацію, представляє її в більш простому для розуміння вигляді.Більше того, вона стає не просто візуальною, але інтерактивною, з нею можна взаємодіяти без написання коду, просто за допомогою інтерфейсу.

За допомогою Swagger UI можна створювати та надсилати запити різних типів, можна швидко переміщатися документацією та тестувати проект. Візуальний інтерфейс можна вбудувати в додаток або розмістити на сторінці, його підтримують усі браузери, тому їм користуються в тому числі для того, щоб роз'яснювати користувачам та клієнтам особливості взаємодії з API.

Swagger Codegen. Ми вже згадували цей компонент вище, він може генерувати код на основі правил. Автоматично згенерований код вирішує лише шаблонні завдання, так що Codegen не замінює програміста, але серйозно полегшує завдання. Він дозволяє позбутися частини рутини.

Swagger Codegen генерує:

• заглушки серверів (server stub) - своєрідні "точки входу" для зовнішніх об'єктів. Ті обмінюються даними із заглушками і таким чином спілкуються із сервером;
• клієнтські бібліотеки API (API clients) — SDK, тобто набори інструментів для розробника, у разі для роботи з API за клієнта;
• документацію з урахуванням наявного коду проекту.

Компонент підтримує безліч мов: Java та ряд фреймворків для нього, C++ та C#, Kotlin, Node.js, Scala, Haskell. Для створення клієнтських бібліотек API також підтримуються Groovy і Bash, а для заглушок серверів - PHP, Python, Ruby і Rust. Генератор документації підтримує HTML та Confluence – вікі-проект для внутрішніх баз знань.

Editor Swagger. Це редактор специфікацій: він дозволяє переглядати написані правила, змінювати та доповнювати їх. Існують онлайн-версія редактора та версія для скачування.Виглядає як розділене на дві частини вікно: ліворуч по специфікації пишеться код опису API, праворуч генерується візуальний інтерфейс Swagger UI. Інтерфейс одночасно інтерактивний і функціональний: можна, не виходячи з редактора, подивитися, як виглядатиме документація. Там же можна протестувати її та одразу внести зміни.

Редактор автоматично перевіряє те, що користувач написав у лівій частині, та вказує на помилки у використанні специфікації. Якщо вони є, це з'явиться в режимі реального часу.

Плюси використання Swagger

• Swagger спрощує та прискорює написання документації, заощаджує час розробників та технічних письменників.
• Можна скоротити рутинну роботу та надати створення шаблонного коду Swagger Codegen: це знову ж таки економить час.
• Документація виходить докладною та ясною для всіх категорій читачів: технічних фахівців, звичайних користувачів та роботів.
• Використовувати Swagger можна досить гнучко: створювати документацію на основі коду або самостійно, застосовувати можливості візуального інтерфейсу для тестування та швидкої навігації.
• Документацію, написану за допомогою Swagger, можна легко вбудувати в сторінку сайту або додаток, і вона буде інтерактивною та повністю функціональною. Але краще все ж таки згорнути свій варіант відображення — стандартний інтерфейс не надто добре вписується в дизайни реальних сайтів.

Мінуси Swagger

Деякі розробники не люблять Swagger, вважають його марним або надмірним, що тільки ускладнює роботу з API. Є думка, що він робить менш наочною комунікацію між бекендерами, що відповідають за серверну частину, та фронтендерами, які створюють клієнтський інтерфейс. Таке справді можливо: Swagger генерує велику кількість коду, і однієї частини команди розробників здається, ніби цього достатньо, тоді як іншій важко в цьому розібратися.Документація не виходить наочною, і це проблема.

Друга причина, через яку Swagger критикують, - відсутність докладної розмітки. Для створення документації багато хто використовує такі інструменти, як Markdown. Вони дозволяють виділяти смислові частини, створювати виноски різні частини документа, додавати якірні посилання. У Swagger таких можливостей немає. Адже створена з ним документація «зсередини» є JSON-файлом, а цей формат у принципі не має на увазі засобів виділення тексту.

Нерідко Swagger порівнюють із іншим інструментом Postman. Обидва інструменти використовуються для роботи з API, але в чому різниця? Вибір інструменту залежить від ваших завдань.

• Якщо потрібно описати API, використовуйте Swagger.
• Якщо вам потрібно тестувати та розробляти API, використовуйте Postman.
• Якщо вам потрібно те й інше, використовуйте Swagger разом із Postman.

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. Опис із документації, думаю, пояснювати не потрібно:

Це є Swagger Codegen project, який дозволяє створювати API клієнтські libraries (SDK generation), сервер листи і документації автоматично given an OpenAPI Spec. Наразі, наступні languages/frameworks є supported:

• API clients: ActionScript, Ada, Apex, Bash, C# (.net 2.0, 3.5 або останній), C++ (cpprest, Qt5, Tizen), Clojure, Dart, Elixir, Elm, Eiffel, Erlang, Go, Groovy, Haskell (http -client, Servant), Java (Jersey1.x, Jersey2.x, OkHttp, Retrofit1.x, Retrofit2.x, Feign, RestTemplate, RESTEasy, Vertx, Google API Client Library for Java, Rest-assured), Kotlin, Lua, Node.js (ES5, ES6, AngularJS з Google Closure Compiler annotations) Objective-C, Perl, PHP, PowerShell, Python, R, Ruby, Rust (rust, rust-server), Scala (akka, http4s, swagger-async- httpclient), Swift (2.x, 3.x, 4.x), Typescript (Angular1.x, Angular2.x, Fetch, jQuery, Node)
• Server stubs: Ada, C# (ASP.NET Core, NancyFx), C++ (Pistache, Restbed), Erlang, Go, Haskell (Servant), Java (MSF4J, Spring, Undertow, JAX-RS: CDI, CXF, Inflector, RestEasy , Play Framework, PKMST), Kotlin, PHP (Lumen, Slim, Silex, Symfony, Zend Expressive), Python (Flask), NodeJS, Ruby (Sinatra, Rails5), Rust (rust-server), Scala (Finch, Lagom, Scalatra)
• API documentation generators: HTML, Confluence Wiki
• Configuration files: Apache2
• Інші: JMeter

Іншу інформацію, зокрема інструкцію з використання, наведено тут:
Загальна інформація

Висновок

Це був короткий наочний огляд для розробників API-початківців, метою якого було надати загальну картину того, що таке Swagger, навіщо він потрібен і які він дає основні плюси з моєї особистої точки зору.