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

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

Swagger изначально разрабатывался компанией SmartBear, а позже стал частью инициативы OpenAPI. Из-за этого их часто путают, но это абсолютно разные вещи:

• Swagger — набор приложений: UI, Editor, Codegen — каждый из которых решает свою задачу.
• OpenAPI Specification (OAS) — это стандарт, определяющий, как следует описывать HTTP-запросы, их параметры и заголовки, а также другие аспекты API.

То есть OAS — это спецификация, а Swagger — инструментарий.

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

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

Как работает Swagger

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

Вот так это выглядит на языке YAML:

Эта спецификация служит документом-контрактом между разработчиками бэкенда, фронтенда и тестировщиками, так как определяет, как именно можно взаимодействовать с сервером. Любой человек, посмотрев на этот YAML-файл, поймет, что у нашего сервера есть эндпоинт /test, у которого можно вызвать метод get.

Приложения из экосистемы Swagger по-разному взаимодействуют с подобными спецификациями. Например:

• Swagger Editor предоставляет веб-интерфейс, в котором программист вручную пишет спецификацию.
• Swagger UI — это тоже веб-сервис, в который загружают готовую спецификацию, чтобы визуализировать методы API в виде обычных кнопок.
• Swagger Codegen — библиотека для Java, которая создает код сервера или клиента с помощью информации, которая есть в спецификации.

В итоге, получается такой рабочий процесс:

1. Аналитик или программист пишет в Editor спецификацию и передает ее разработчикам.
2. Программисты видят в спецификации, какие эндпоинты и методы должны быть у сервера, и на основе этого пишут код.
3. Когда работа закончена, тестировщики используют Swagger UI, чтобы проверить работу эндпоинтов и ответы сервера.

Что такое API и как с ним связан Swagger

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

При этом серверу все равно, кто является клиентом, главное — чтобы ему прислали верный запрос. Поэтому API стараются максимально стандартизировать и задокументировать. Один из таких стандартов — Rest. Это подход к проектированию API, который использует протокол HTTP и его методы — GET, POST, PUT, DELETE и др. При этом REST не привязан к конкретному языку или технологии.

В REST всё строится вокруг ресурсов (/users, /products), к которым обращаются по URI. Например, «site.com/users» — это обращение к ресурсу /users.

Как Swagger связан с Rest API

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

Здесь на помощь приходит Swagger — инструмент, который автоматически создает и поддерживает актуальную документацию API в стандартизированном формате (YAML/JSON). Это обеспечивает единый источник правды для всех, кто работает с API.

Например, вот так выглядит описание в Swagger UI. Здесь можно увидеть все эндпоинты и HTTP-методы, по которым клиенты обращаются к серверу:

При этом с помощью Swagger UI можно не просто прочитать документацию, а сразу «пощупать» API — отправить запрос и увидеть ответ прямо в браузере. Также инструмент предоставляет полную информацию об эндпоинте, параметрах, которые он принимает, и возможных статус-кодах ответа. Например, для метода «/user/{username}/» — get user by user name (вторая строка на скрине выше) — доступен один параметр и три статус-кода ответа:

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

Компоненты Swagger

Как уже говорили выше, Swagger — это общее название для инструментов. В экосистему входят разные инструменты:

• Есть веб-приложения: Swagger Editor, Swagger UI. Их также можно скачать и запустить локально;
• Есть фреймворки для конкретных языков Swagger Core для Java, NSwag для .Net, go-swagger для Go.
• Также есть платные инструменты SwaggerHub, Swagger Inspector и т. д.

Разберем три самых популярных.

Swagger Core

Этот инструмент ориентирован на Java. Представляет собой набор библиотек и аннотаций, которые позволяют разработчикам автоматически генерировать спецификацию к API. Например, вы пишете REST-контроллеры на Java, добавляете аннотации «@Api», «@ApiOperation», «@ApiResponse» и другие. Swagger Core анализирует их и генерирует описание API в формате JSON или YAML.

Вот пример такого контроллера:

@RestController
@RequestMapping("/api/users")
public class UserController {
    private List<String> users = new ArrayList<>();
    @ApiOperation(value = "Получить список всех пользователей")
    @ApiResponses(value = {
            @ApiResponse(code = 200, message = "Список успешно получен"),
            @ApiResponse(code = 500, message = "Ошибка сервера")
    })
    @GetMapping
    public List<String> getAllUsers() {
        return users;
    }
}

Здесь мы добавляем контроллер UserController, внутри которого находится список пользователей. Его можно получить с помощью метода getAllUsers(). Обратите внимание, что у этого метода есть аннотации, которые добавляет Swagger Core:

• @ApiOperation — описание метода;
• @ApiResponses — возможные ответы сервера.

Эти аннотации нужны, чтобы на их основе создать YAML иди JASON спецификацию, которую затем можно передать тестировщикам и другим программистам. Делается это с помощью класса SwaggerConfiguration() и GenericOpenApiContextBuilder().

Минус такого подхода: код становится слишком большим из-за множества аннотаций и комментариев.

Swagger Editor

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

Рассмотрим интерфейс редактора подробнее:

• Слева находится текстовый редактор, где можно писать спецификацию на языке YAML или JSON (на скрине используется первый формат).
• Правая часть — визуальное представление API. Здесь можно просмотреть всю информацию об эндпоинте: какие HTTP-методы он принимает и что возращает.

В Editor создавать документацию гораздо легче, чем в Core, так как вам не нужно разбираться в программировании. Однако Core может генерировать документацию на основе готового кода, а в Editor придется писать вручную. Из-за этого Editor больше используют аналитики, а не разработчики.

Swagger UI

Приложение, как и Editor, отображает документацию для API в виде интерактивного меню. Оно преобразует спецификацию OpenAPI (в формате YAML или JSON) в наглядный веб-интерфейс, где можно просматривать эндпоинты, параметры, модели данных и примеры ответов.

Одна из ключевых особенностей этого инструмента — возможность протестировать любой метод. Например, на скрине ниже показано, что пользователь может проверить работоспособность метода POST, который загружает картинку на сервер, всего одной кнопкой Try it out.

Это удобно, так как тестировщик может прямо из Swagger узнать, как сервер справляется с большими изображениями, правильно ли обрабатывает пользовательский ввод и т. д.

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

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

Создаем спецификацию

Для примера возьмем онлайн-версию инструмента, которая находится по адресу https://editor.swagger.io/. Откроется такая страница:

Слева находится редактор, где мы будем писать спецификацию, а справа Swagger будет рендерить графическое представление. Для работы вам может потребоваться документация OpenAPI/, где описываются основные блоки YAML и JSON.

Спецификация начинается:

• с блока «openapi», где указывается версии OpenAPI;
• блока info, где указывается основная информация о нашем веб-сервисе;
• и блока paths, куда заносится информация обо всех эндпоинтах.

Эти блоки — обязательные, без них сервис выдаст ошибку. Вот как это выглядит в коде:

openapi: 3.0.3
info:
  title: Сервис погоды
  version: 1.0.0
paths: {}

В первой строке указывается версия OpenAPI. В строке 2-4 записан блок «info» с параметрами «title» и «version». Также в этом блоке можно указать дополнительную информацию о нашей компании: описание, адрес, телефон и т. д. Ниже находится пустой блок «paths».

Обратите внимание на правую часть экрана. Swagger Editor подхватывает все изменения в YAML и на лету рендерит понятное человеку представление. Например, создадим описание для нашего API. Для этого добавим блок «description»:

Теперь создадим эндпоинт, например, «/weather», который будет принимать обязательный параметр «city»:

В блоке «paths» указываем эндпоинт «/weather». Далее пишем:

• get: — метод HTTP-запроса, означает, что мы хотим получить данные;
• summary — краткое описание;
• description — подробное описание;
• parameters: — параметры, которые принимает запрос;
• name: city — этой строкой указывает, что параметр называется «city»;
• in: query — параметр передается в строке запроса (?city=Moscow);
• required: true — показывает, что это обязательный параметр;
• schema — тип параметра (string).

Также обязательно нужно указать блок «responses», в котором прописывается статус-код ответа сервера «200». Далее прописывается:

• content: application/json: — обозначает формат ответа JSON;
• schema — схема возвращаемого объекта;
• city (строка);
• temperature (число с плавающей точкой);
• condition (строка, например «Cloudy»).

Вы также можете указать свои параметры, которые будут возвращаться в ответе, или указать реакцию эндпоинта на другие статус-коды. Например, напишем реакцию на «400» и «404».

Полный код спецификации:

openapi: 3.0.3
info:
  title: Weather API
  version: 1.0.0
  description: Простое API для получения информации о текущей погоде по названию города.
paths:
  /weather:
    get:
      summary: Получить текущую погоду
      description: Возвращает данные о текущей погоде для указанного города.
      parameters:
        - name: city
          in: query
          description: Название города, для которого нужно получить погоду.
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Успешный ответ с информацией о погоде
          content:
            application/json:
              schema:
                type: object
                properties:
                  city:
                    type: string
                    example: Moscow
                  temperature:
                    type: number
                    format: float
                    example: 12.5
                  condition:
                    type: string
                    example: "Cloudy"
'400':
          description: Некорректный запрос — отсутствует параметр city или неверный формат
'404':
          description: Город не найден

Смотрим, что получилось

Теперь рассмотрим визуализацию методов, которую выдает Swagger на выходе (в правой части экрана). Приложение сгенерировало удобное представление нашего get-запроса. Чтобы увидеть подробности, нажмите на значок стрелки:

Мы увидим описание запроса, параметры, которые он принимает, и возможные ответы:

Вы можете сами поэкспериментировать со Swagger: добавить другие типы запросов POST, DELETE и написать больше эндпоинтов.

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

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

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