Swagger

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

Логотип Swagger

На основе кода или набора правил Swagger автоматически генерирует документацию в формате JSON-файла. Ее можно встроить на страницу сайта или в приложение, чтобы пользователи могли интерактивно знакомиться с документацией, можно отправлять клиентам — сгенерировать такое описание намного быстрее, чем написать с нуля.

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

Название читается как «Сваггер». Альтернативное название — OpenAPI. Так называется спецификация, по которой работает Swagger, но иногда название применяют при описании продукта.

Кто пользуется Swagger

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

Для чего нужен Swagger

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

Разработка API. Swagger используется, когда, например, разработчику нужно свериться с документацией при доработке продукта, или он хочет сгенерировать ее из кода. Иногда требуется обратный процесс — генерация кода на основе документации, возможная благодаря компоненту Swagger Codegen. Мы поговорим о нем ниже.

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

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

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

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

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

Swagger работает на основе спецификации OpenAPI 3.0. Раньше она тоже называлась Swagger, но ее переименовали в 2015 году, когда проект передали другой команде разработчиков.

Спецификация — набор правил, которые описывают, как должна выглядеть и работать та или иная технология. Это теоретический «каркас» для будущего программного проекта. На его основе пишется код, реализация, которая работает по описанной в спецификации логике. Соответственно, OpenAPI — это набор правил и стандартов для описания API.

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

Как устроена спецификация

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

<название объекта>: <значение>

или

<название объекта>:

<название вложенного объекта>: <значение>

<название вложенного объекта>: <значение>

И так далее.

Объект может представлять собой, например, имя пользователя, название модуля, ссылку или что-то еще. Основных объектов восемь; остальные вложены в них:

  • openapi. Его значение — версия OpenAPI, которая используется в проекте;
  • info. Включает в себя вложенные объекты, которые содержат основную информацию об API: название, описание, лицензию, контакты разработчиков и т.д.;
  • servers. Включает в себя ссылки, ведущие к серверам, — базовые пути для доступа извне без учета конечных точек;
  • paths. Описывает конечные точки, или эндпоинты (end points) — конец пути к той или иной сущности. Для каждого эндпоинта прописываются запросы GET, POST, DELETE и PUT — операции для взаимодействия с сущностью;
  • components. В нем хранятся схемы, которые могут использоваться в разных местах документации. Например, можно создать схему «Пользователь» с полями «Имя», «Адрес» и другими. После описания в components схему можно использовать дальше в коде документации;
  • tags. Хранит метаданные тегов: заголовок, описание и так далее. Помогает более подробно описывать происходящее;
  • security. Описывает методы для обеспечения безопасности, которые можно использовать с API;
  • externalDocs. Содержит ссылки на внешнюю документацию, обычно с дополнительной информацией. Например, это может быть документация какого-то стороннего инструмента, который используется в коде.

Четыре компонента 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 — вики-проект для внутренних баз знаний.

Swagger Editor. Это редактор спецификаций: он позволяет просматривать написанные правила, изменять и дополнять их. Существуют онлайн-версия редактора и версия для скачивания. Выглядит он как разделенное на две части окно: слева по спецификации пишется код описания API, справа генерируется визуальный интерфейс Swagger UI. Интерфейс одновременно интерактивен и функционален: можно, не выходя из редактора, посмотреть, как будет выглядеть документация. Там же можно протестировать ее и сразу внести изменения.

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

Плюсы использования Swagger

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

Минусы Swagger

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

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

Как начать работать со Swagger

Редактором Swagger можно пользоваться онлайн. Также можно скачать его: все бесплатные компоненты проекта доступны на GitHub и на официальном сайте. Для корректной работы понадобится Java и несколько фреймворков — мы описали технологии выше.

Есть проект SwaggerHub, облачная платформа, которая позволяет использовать возможности Swagger онлайн. Для доступа к ней предлагается три тарифных плана. План Free — бесплатный; платные планы Teams и Enterprise предназначены для компаний. Так что начинающий разработчик может пользоваться проектом и не платить за него.

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

(рейтинг: 5, голосов: 2)
Добавить комментарий