<div><img src="https://top-fwz1.mail.ru/counter?id=3548135;js=na" style="position:absolute;left:-9999px;" alt="Top.Mail.Ru" /></div>
Публичное облако на базе VMware с управлением через vCloud Director
Вход / Регистрация

Что такое Swagger и как он облегчает работу с API

Миша Курушин
Миша Курушин
Технический писатель
02 апреля 2025 г.
228
15 минут чтения
Поделиться
Средний рейтинг статьи: 5

Swagger (читается «сваггер») — это универсальный набор инструментов для проектирования, документирования, тестирования и развертывания REST API на основе общепринятых стандартов OpenAPI и AsyncAPI.

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

Image3

API vs REST API

API (Application Programming Interface) — это набор правил и инструментов для взаимодействия разных приложений друг с другом. Он определяет, как одна программа может запрашивать данные или функциональность у другой.

Например, вызов метода из математического модуля языка программирования Python является наипростейшей формой локального API, с помощью которого разные компоненты программы могут обмениваются данными друг с другом:

import math # импорт математического модуля

result = math.sqrt(16) #  вызов метода API математического модуля для вычисления квадратного корня

print(f"Квадратный корень из 16 равен {result}") # вывод в консольный терминал результата вычисления

В данном случае модуль math предоставляет набор функций для работы с математическими операциями, а функция sqrt() является частью интерфейса, скрывающего внутреннюю реализацию модуля.

REST API — это API, следующий принципам архитектуры REST (Representational State Transfer), в которой взаимодействие с ресурсами другой программы осуществляется через HTTP-запросы (GET, POST, PUT, DELETE), представленные в виде URL-адресов (энд поинтов или end points).

Например, получение, отправка, удаление и изменение контента на сайтах в Интернете выполнятся через отправку соответствующих запросов по конкретным URL с указанием дополнительных параметров, если таковые требуются:

  • Получение главной страницы
    • GET / HTTP/1.1
    • Host: site.ru
  • Получение первой страницы со списком статей
    • GET /site.ru/page/1 HTTP/1.1
    • Host: site.ru
    • ...
  • Получение второй страницы со списком статей
    • GET /site.ru/page/2 HTTP/1.1
    • Host: site.ru
    • ...
  • Публикация новой статьи
    • POST /site.ru/newarticle HTTP/1.1
    • Host: site.ru
    • ...
  • Удаление существующей статьи
    • DELETE /site.ru/article/nekaya-lishnya-statya HTTP/1.1
    • Host: site.ru
    • ...

Таким образом, REST API является расширением API, которое указывает на конкретный тип взаимодействия между программами.

vds

OpenAPI vs AsyncAPI

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

На данный момент популярны два стандарта. Один описывает синхронный API, другой — асинхронный:

  • OpenAPI. Предназначен для REST API. Представляет собой синхронную отправку сообщений (GET, POST, PUT, DELETE) по протоколу HTTP. Все сообщения последовательно обрабатываются сервером. Например, интернет-магазин, отправляющий страницы со списком товаров по каждому запросу пользователя.

  • AsyncAPI. Предназначен для Event-driven API. Представляет собой асинхронную отправку сообщений по протоколам MQTT, AMQP, WebSockets, STOMP, NATS, SSE и другим. Каждое отдельное сообщение передается брокером сообщений определенному обработчику. Например, чат-приложение, отправляющее сообщения пользователей через WebSockets.

Несмотря на архитектурные различия, оба стандарта позволяют описывать API приложений в виде спецификации в двух форматах на выбор — JSON или YAML. Такая спецификация может быть прочитана как человеком, так и компьютером.

Структура спецификация OpenAPI имеет следующий вид:

  • openapi. Версия спецификации.
  • info. Основная информация об API.

    • title. Название API.

    • version. Версия API.

    • description. Краткое описание API.

    • termsOfService. Ссылка на условия использования.

    • contact. Контактная информация.

    • license. Информация о лицензии.

    • externalDocs. Ссылки на внешние документации.

    • tags. Метаданные тегов для более подробного описания API.

  • servers. Адреса серверов, обрабатывающих запросы API.

    • url. Адрес сервера.

    • description. Описание сервера.

  • paths. Точные адреса по которым совершаются запросы API.

    • get / post / put / delete. Методы HTTP-запроса.

    • summary / description. Описание запроса.

    • parameters. Список параметров запроса.

    • requestBody. Тело запроса.

    • responses. Разрешенные ответы API.

  • components. Предопределенные элементы, которые могут быть использованы в нескольких местах документации.
  • schemas. Описание моделей данных.
  • securitySchemes. Описание моделей аутентификации.
  • security. Механизмы аутентификации API.

Полное описание спецификации можно посмотреть на официальном сайте OpenAPI.

Вот пример простой спецификации OpenAPI в формате YAML:

openapi: 3.0.0
info:
  title: Простое приложение
  description: Это всего лишь простое приложение
  version: 1.0.1
servers:
  - url: http://api.site.ru/
    description: Основное API
  - url: http://devapi.site.ru/
    description: Дополнительный API
paths:
  /users:
    get:
      summary: Лист с пользователями
      description: Это импровизированный список существующих пользователей
      responses:
        "200":
        description: Список пользователей в формате JSON
        content:
          application/json:
            schema:
              type: array
                items:
                type: string

Структура спецификации AsyncAPI имеет следующий вид:

  • asyncapi. Версия спецификации.

  • info. Основная информация об API.

    • name. Имя.

    • email. Почта.

    • name. Название.

    • url. Ссылка.

    • description. Описание.

    • url. Ссылка.

    • name. Название.

    • description. Описание.

    • title. Название.

    • version. Версия.

    • description. Описание.

    • termsOfService. Ссылка на условия использования.

    • contact. Контактная информация.

    • license. Информация о лицензии.

    • externalDocs. Документация.

    • tags. Список тегов.

  • servers. Сервера, обрабатывающие запросы API.

    • type. Тип.

    • scheme. Метод.

    • name. Название.

    • description. Описание.

    • description. Описание.

    • url. Ссылка.

    • host. Адрес.

    • title. Название.

    • description. Описание.

    • summary. Краткое описание.

    • pathname. Путь.

    • protocol. Протокол.

    • protocolVersion. Версия протокола

    • security. Методы авторизации.

    • tags. Список тегов.

    • externalDocs. Документация.

    • bindings. Дополнительные параметры протоколов.

  • channels. Способы связи для отправки сообщений.

    • name. Название.

    • description. Описание.

    • description. Описание.

    • url. Ссылка.

    • address. Адрес.

    • parameters. Параметры.

    • title. Название

    • description. Описание.

    • summary. Краткое описание.

    • messages. Возможные сообщения.

    • servers. Серверы, для которых доступен этот канал.

    • tags. Список тегов.

    • externalDocs. Документация.

    • bindings. Дополнительные параметры протоколов.

  • operations. Действия для выполнения приложением.

    • type. Тип.

    • scheme. Метод.

    • type. Тип.

    • scheme. Метод.

    • name. Название.

    • description. Описание.

    • description. Описание.

    • url. Ссылка.

    • action. Тип операции в канале (send или receive)

    • channel. Канал операции.

    • title. Название

    • description. Описание.

    • summary. Краткое описание.

    • security. Методы авторизации.

    • security. Методы авторизации.

    • tags. Список тегов.

    • externalDocs. Документация.

    • bindings. Дополнительные параметры протоколов.

    • traits. Свойства.

    • messages. Сообщения.

    • reply. Ответы.

  • components. Повторно используемые структуры спецификации.

Полное описание спецификации можно посмотреть на официальном сайте AsyncAPI.

Вот пример простой спецификации AsyncAPI в формате YAML:

asyncapi: 3.0.0
info:
  title: 'Простое приложение’
  description: 'Это всего лишь простое приложение'
  version: '1.0.1'
channels:
  some:
  address: 'some'
  messages:
    saySomething:
      payload:
        type: string
        pattern: '^Вот тебе фразочка: .+$'
operations:
  something:
    action: 'receive'
    channel:
      $ref: '#/channels/some'

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

Таким образом, спецификация — это набор формальных правил, по которым работает интерфейс взаимодействия с приложением.

Именно в этот момент на сцену и выходят такие инструменты, как Swagger. С помощью них можно управлять спецификацией API в наглядном виде — редактировать, визуализировать и тестировать.

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

Инструменты Swagger

Стремясь покрыть широкий спектр задач по работе с API, Swagger предоставляет инструменты с разной зоной ответственности:

  • Swagger UI. Браузерный инструмент для визуализации спецификации. Позволяет отправлять запросы к API прямо из браузера, поддерживает авторизацию через API-ключи, OAuth, JWT и другие механизмы.

  • Swagger Editor. Браузерный инструмент редактирования спецификации с визуализацией в режиме реального времени. Редактирует документацию, подсвечивает синтаксис, выполняет автодополнение, валидирует API.

  • Swagger Codegen. Консольный инструмент для генерации серверного и клиентского кода на основе спецификации. Генерирует код на JavaScript, Java, Python, Go, TypeScript, Swift, C# и других языках программирования. Также отвечает за генерацию интерактивной документации, доступной из браузера.

  • Swagger Hub. Облачный инструмент для совместной работы через Swagger UI и Swagger Editor. Хранит спецификации на облачных серверах, выполняет версионирование, интегрируется с CI/CD-конвейерами.

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

Image2

Список всех инструментов Swagger доступен на официальном сайте

Кому и зачем нужен Swagger

Итак, выше мы рассмотрели, что такое сваггер и как он связан с REST API. Теперь стоит поговорить о том, кому и зачем он может понадобиться.

Основные пользователи Swagger — разработчики, системные аналитики и технические писатели. Первые разрабатывают API, вторые его анализируют, третьи — документируют. Соответственно, Swagger может быть использован в следующих задачах:

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

  • Взаимодействие с API. Swagger помогает в тестировании API, позволяя отправлять запросы с выбранными параметрами по точным адресам прямо из браузера.

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

Вот именно для такой поэтапной работы над API и нужен Swagger со всеми своими инструментами.

Как пользоваться Swagger

Будучи экосистемой, Swagger выполняет множество функции, связанных с разработкой и поддержкой API.

Редактирование спецификации

Для интерактивного редактирования спецификации REST API в Swagger существует специальный инструмент — Swagger Editor.

Image1

Интерфейс Swagger Editor: слева текстовое поля для редактирования спецификации, справа — визуализация актуальной документации.

Для работы над спецификацией можно использовать онлайн-версию классического Swagger Editor либо обновленного Swagger Editor Next.

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

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

Image5

Более информативный интерфейс Swagger Editor Next. В глаза бросается миникарта кода и обновленный дизайн документации.

Разумеется, предпочтительно использовать локальную версию редактора. Процесс установки Swagger Editor и Swagger Editor Next подробно описан в официальной документации Swagger.

Визуализация спецификации

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

Подробная инструкция для установки Swagger UI на локальный сервер доступна в официальной документации Swagger. Там же можно протестировать демонстрационную панель Swagger UI.

Image4

Страница демонстрационной панели Swagger UI, которая визуализирует тестовую спецификацию

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

Генерация документации

На основе спецификации инструмент Swagger Codegen может сгенерировать документацию API в формате HTML-страницы.

Загрузить Swagger Codegen можно с официального сайта Swagger. Введение в процесс генерации различных данных доступно в репозитории GitHub. А исчерпывающая информация с примерами размещена в документации.

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

Автоматический разбор аннотаций выполняется с помощью сторонних библиотек. Для разных языков программирования применяются разные библиотеки. Среди них:

  • Gin-Swagger для Go с фреймворком Gin
  • Flask-RESTPlus для Python с фреймворком Flask
  • Swashbuckle для C# и .NET с фреймворком ASP.NET Core
  • FastAPI для Python

Работает это примерно так:

  • Подключение библиотеки. Разработчик подключает к исходному коду приложения библиотеку генерации спецификаций.

  • Создание аннотаций. В тех местах исходного кода, где выполняется обработка (роутинг) запросов API, разработчик добавляет вызовы специальных функций из подключенной библиотеки. В них указываются данные о конкретном эндпоинте: адрес, параметры, описание и т.п.

  • Генерация спецификации. Разработчик запускает приложение, функции с информации об API выполняются, и на выходе получается готовый файл спецификации в формате YAML или JSON. Впоследствии он передается в один из инструментов Swagger. Например, в Swagger UI для визуализации документации.

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

Например, можно генерировать спецификацию в FastAPI, редактировать в Swagger Editor, а визуализировать в ReDoc.

Генерация кода

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

Однако, надо понимать, что сгенерированный код довольно примитивен и едва ли подходит для использования в продакшене. На то есть несколько фундаментальных причин:

  • Отсутствие бизнес-логики. Сгенерированный код по своей сути ничего не делает. Это своего рода заглушки, простейшие обработчики запросов, подходящие для быстрого тестирования API.

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

  • Низкая безопасность. В сгенерированном коде нет никаких проверок и защиты от различных типов атак.

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

Тестирование API

Через Swagger UI можно выбрать конкретной адрес (эндпоинт) с заданными параметрами, чтобы совершить тестовый запрос к серверу программного продукта, который отвечает за обработку API.

В этом случае Swagger UI будет визуально выводить HTTP-ответы, явно показывая коды ошибок, заголовки и тела сообщений.

Это избавляет от написания специальных сниппетов кода, совершающих тестовые запросы и обрабатывающих их ответы.

Альтернативы Swagger

Swagger — это не единственный инструмент для работы с API. Есть и несколько других со схожим функционалом:

  • Postman. Мощный инструмент для разработки, тестирования и документации REST и SOAP API. Позволяет отправлять HTTP-запросы, анализировать ответы, автоматизировать тестирование и генерировать документацию.

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

  • Redoc. Инструмент для генерации интерактивной документации, доступной из браузера, на основе спецификации OpenAPI.

  • Apigee. Платформа для разработки, управления и мониторинга API, принадлежащая компании Google и являющаяся частью Google Cloud Platform.

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

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

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

Надежные VDS/VPS для ваших проектов

Заключение

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

При этом, помимо классических консольных представлений, API в Swagger визуализируется в наглядном виде через браузер, делая Swagger пригодным для «чайников», которые только начинают свой путь в разработке.

Если же какой-то из инструментов Swagger не подходит под конкретный проект, он может быть заменен альтернативным, ведь API приложения описывается в стандартизированных форматах OpenAPI или AsyncAPI, которые поддерживаются множеством других инструментов.

Исчерпывающую информацию об инструментах Swagger можно найти в официальной документации Swagger. Там же представлены различные туториалы по Swagger.

02 апреля 2025 г.
228
15 минут чтения
Поделиться
Средний рейтинг статьи: 5
API Разработка Swagger
Пока нет комментариев