Swagger

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

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

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 — о нем мы подробнее расскажем ниже.

Что такое спецификация 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. Содержит ссылки на внешнюю документацию, обычно с дополнительной информацией. Например, это может быть документация какого-то стороннего инструмента, который используется в коде.

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/{taskId}:
    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: taskId
          in: path
          required: true
          description: ID задачи
          schema:
            type: string
      requestBody:
        description: Обновленные данные задачи
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/NewTask'
      responses:
        '200':
          description: Задача успешно обновлена
          content:
            application/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/{taskId})
• Обновить задачу по ID (PUT /tasks/{taskId})
• Удалить задачу по ID (DELETE /tasks/{taskId})

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

Swagger Editor. Это редактор спецификаций: он позволяет просматривать написанные правила, изменять и дополнять их. Существуют онлайн-версия редактора и версия для скачивания. Выглядит он как разделенное на две части окно: слева по спецификации пишется код описания 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 оказался незаменимым инструментом для документирования API. Я использовала его для создания ясной и понятной документации, которая помогает как мне, так и другим разработчикам быстро понимать, как работает наше API.

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

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

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

Мой опыт использования Swagger в сочетании с Symfony был очень положительным. Он значительно упрощает разработку, тестирование и поддержку API. Конечно, у него есть свои недостатки, но они не перевешивают те преимущества, которые он приносит в работу команды. Я бы рекомендовала его к использованию любому разработчику, работающему с API.

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

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

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

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

Что такое Swagger простыми словами

Swagger — это инструмент для подготовки документации и тестирования API. 

Swagger можно разделить на четыре основных компонента: Swagger Core, Swagger UI, Swagger Codegen, Swagger Editor.

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

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