Из чего состоит Swagger (OpenAPI) документ и как с ним работать

Бизнес и системные аналитики часто работают с документацией, описывающей API различных сервисов. Если их (сервисов) в компании больше двух и они обмениваются между собой данными в архитектурном стиле REST, есть смысл изучить фреймворк Swagger, также известный как OpenAPI.

Основные преимущества ведения REST API документации в Swagger:

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

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

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

Здесь я старался подробно раскрыть следующие вопросы:

1. Из чего состоит Swagger документ?
2. Как его читать?
3. Способы формирования документации? 
4. Как и где Swagger может быть использован?
5. Как самостоятельно описать API для Swagger.

Когда бизнес или системный аналитик может встретиться со Swagger документацией в работе

Примеры рабочих задач:

Аналитику в работу поступает задача на доработку существующего в компании сервиса. Необходимо добавить новый или отредактировать действующий функционал.

Аналитик хочет понять как сейчас работает сервис и разработчик/другой аналитик/руководитель проекта отправляет его в swagger читать описание API, изучать атрибутивный состав объектов и доступные методы.

---

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

---

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

---

Аналитик проектирует новый сервис, который будет получать данные другого “нашего” сервиса, документация которого описана в Swagger.

---

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

---

Еще один пример того, как системному аналитику пригодился Swagger и, заодно, отзыв первого читателя этой статьи — Александра Кротова:

Я к Сваггеру пришел почти случайно. Сейчас почти подготовил три обучающих встречи в клубе (вне)системных аналитиков на тему интеграции. Одна из них про api. Идея была в том, чтобы взять маленькое (из лягушатника!) api и рассмотреть его с разных сторон:

— как api видит клиент, как получает данные, отправляя, разные правильные и неправильные запросы;

— как api выглядит с серверной части, как принимаются запросы, проверяются данные и выполняются соответствующие действия;

— как api взаимодействует с БД, т.е. как строится api уровня БД (представления, процедуры и пр.)

А потом понял, что начать неплохо было бы с документации, по которой можно изучить api перед началом использования. Чтобы не говорить: “Забейте в Postman такие-то параметры…”, а брать эти данные из документации. Конечно, можно было и в текстовом варианте это сделать, но мне показалось, что это как-то несовременно. Подумал, что неплохо сделать в Swagger, т.к. в основном натыкаюсь на него, когда чужие api смотрю. Но сам никогда ничего в нем не делал. Чуть-чуть почитал, понял, что неохота разбираться — в долгострой уйду. А тут ваша статья. Тут уже деваться оказалось некуда 🙂 Теперь я через Swagger добавляю данные в БД через api 🙂

Из чего состоит Swagger документ

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

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

Привычный вид интерактивного интерфейса документу придает компонент Swagger UI.

Интерактивная документация позволяет в удобном формате просматривать все доступные на сервисе методы и тестировать их, путем отправки запросов и просмотра ответов.

Способы формирования Swagger документации

Существует несколько способов формирования: 

1. Аналитик пишет вручную Swagger документацию и готовый API прикрепляет к требованиям для разработчиков. 
2. Аналитик формирует требования к API в виде набора атрибутов и логики запросов, а разработчик формирует “рабочий код приложения” на основе которого генерирует Swagger документацию.

Первым способом (вручную) чаще формируют документацию для небольших микросервисов. Если таковых много, то желательно перечислить их на одном, доступном всем аналитикам, ресурсе. Для каждого сервиса указывается:

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

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

Итоговый выбор способа документирования всегда – результат договора команды. 

Форматы, используемые при описании Swagger документа

Swagger документ может быть описан в форматах YAML или JSON. От формата данных структура не изменяется. Различается только стиль описания. Я рекомендую учиться работать сразу с JSON форматом, так как в REST запросах обмен данными выполняется чаще всего именно в нем.

Можно освоить какой-то конкретный синтаксис и, при необходимости, “перегонять” данные из одного формата в другой, используя любой из доступных в сети конвертеров данных.

Пример ресурса для конвертации данных можете найти по запросу “json to yaml” (или наоборот).

Инструменты

Есть множество инструментов для формирования OpenAPI документации вручную:

1. Online редакторы. Один из них https://editor.swagger.io/
2. Инструменты, инсталлируемые локально на компьютер.
   Например, расширения “Swagger Viewer” или “OpenAPI (Swagger) Editor” для VS Code
3. Макрос “Open API (Swagger) Integration for Confluence”, позволяет писать документацию для API сразу в Confluence.

Практика

Чтобы показать как происходит формирование документации на практике, ниже в статье я привел пример того, как можно вручную описать API для сервиса, предоставляющего пользователям методы создания, редактирования и просмотра баннеров. Реализация происходит с использованием HTTP глаголов: GET, POST, PATCH. Такой набор методов можно применить и к другим предметным областям, так как это наиболее популярные REST запросы.

Описание предметной области

Есть 2 вида баннеров с одинаковым набором атрибутов, но разных внешне. Набор атрибутов следующий:

• заголовок;
• основной текст;
• картинка;
• категория баннера;
• видимость баннера;
• ссылка для перехода на страницы подробной информации;
• уникальный ID экземпляра объекта.

Frontend получает весь список баннеров методом GET. Баннер отображается в различном дизайне и в разных местах экрана в зависимости от его категории.

Также необходимо реализовать методы для создания новых баннеров (POST) и редактирования параметров существующих (PATCH). 

Установка расширения OpenAPI (Swagger) Editor для VS Code

Установка расширения “OpenAPI (Swagger) Editor” выполняется в 3 шага:

1. Откройте в VS Code вкладку “Расширения”
2. Найдите расширение по названию “OpenAPI (Swagger) Editor”
3. Установите расширение

Помимо основной задачи “Сформировать Swagger документацию”,  расширение добавляет на боковую панель VS Code дополнительный раздел “OpenAPI”. С его помощью удобно быстро переходить к нужному фрагменту документа.

Старт проекта

После установки расширения нажмите сочетание клавиш Ctrl+Shift+P (на Windows) или Cmd+Shift+P (на  Mac). Откроется командная строка, в которой нужно написать “Create new OpenAPI v3.0 file” и нажать Enter.

После выполнения команды откроется новый файл с заполненным “каркасом” документа.

{
   "openapi": "3.0.2",
   "info": {
       "title": "API Title",
       "version": "1.0"
   },
   "servers": [
       {
           "url": "https://api.server.test/v1"
       }
   ],
   "paths": {}
}

Далее сохраните файл (“Cmd+S” на Mac или “Файл => Сохранить”) в формате json в удобном месте.

Из чего состоит базовый шаблон Swagger документа 

Запись «openapi»: «3.0.2» сообщает, что документ описан в спецификации OpenAPI “3.0”. Это самая актуальная стабильная версия на момент написания статьи. Также есть версия “2.0” — устаревшая и “3.1” — экспериментальная. От версии OpenAPI зависит структура документа и доступность некоторых функций.

Объект «info» содержит параметры по умолчанию: «title» — заголовок и «version» — версия именно нашего API. От себя я дописал атрибут «description» в котором подробнее написано о реализуемом API. 

"info": {
       "title": "Banners",
       "version": "API 1.0",
       "description": "API for managing banners"
   },

Объект «servers» описывает на каких серверах доступна реализация проектируемого API. Данную информацию могут предоставить программисты после разработки сервиса и ее нужно будет добавить в документацию. На этапе проектирования я всегда указываю серверы “заглушки”. 

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

Для каждого сервера я заполнил атрибуты:

• «url»  — URL-адрес конечного узла;
• «description» — описание назначения сервера

 "servers": [
       {
           "url": "https://api.example.com/v1",
           "description": "Production server"
       },
       {
           "url": "https://test-api.example.com",
           "description": "Test server"
       }
   ],

В объекте «paths» хранится вся информация о доступных в API методах и их реализации. 

С помощью сочетания клавиш Option+Shift+P (на  Mac) или Alt+Shift+P (на Windows) запускается компилятор и формируется интерактивное представление документа.

Для удобства чтения “схемы”, стрелками обозначил какая информация из документа в каком месте отображается.

Описания “Конечных точек” и HTTP заголовков документа

“Конечные точки” и HTTP заголовки указываю внутри объекта «paths».

По заданию нужно реализовать методы:

1. Получение списка баннеров (GET /banners).
2. Создание нового баннера (POST /banners).
3. Обновление параметров существующих баннеров (PATCH /banners/{id}).

Для реализации данных методов я использую “Конечные точки” (endpoints):

• «/banners» – для получения списка баннеров и создания нового баннера
• «/banners/{id}» – для обновления параметров баннеров. В параметр {id} передается “id” конкретного баннера, который нужно отредактировать.

HTTP заголовки (get, post, patch) указываю внутри “Конечных точек”.

   "paths": {
       "/banners": {
           "get": {},
           "post": {}
       },
       "/banners/{id}": {
           "patch": {}
       }
   }

Запускаю компилятор и проверяю результат

Описание параметров API для запросов и ответов методов

В каждом методе заполняю информацию:

• «tags» – использую для группировки методов по типу объекта. Обычно используется один тег на несколько методов.
• «summary» – краткое описание метода, которое отображается рядом с названием HTTP глагола
• «operationId» — уникальный идентификатор операции. Используется для точной идентификации метода при разборе ошибок. Идентификатор должен быть уникальными среди всех операций, описанных в API. 

Для методов получения списка баннеров и обновления баннера, дополнительно в объекте «parameters» описываю параметры, с которыми эти методы могут быть вызваны. 

Подробней про объект «parameters» вы можете почитать в документации.

Ниже приведен пример заполнения параметров для GET запроса

“Тело запроса” и содержание ответа для методов описывается в объектах:

• «requestBody» — тело запроса
• «responses» — ответ на запрос

Для методов создания (POST) и обновления (PATCH) баннера в «requestBody» передаю набор всех параметров баннера, кроме ID. 

При создании баннера его ID будет генерироваться автоматически на уровне базы данных. 

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

При выполнении запроса, указанные в «requestBody» параметры будут отправлены на сервер. Как при создании нового, так и при обновлении существующего баннера, успешное выполнение запроса приведет к обновлению записей в базе данных сервиса. 

Для метода получения списка баннеров (GET) «requestBody» не заполняется, так как GET запрос, только получает имеющиеся данные с сервера, а не создает/обновляет записи, как делают POST и PATCH.

Подробней почитать про объект «requestBody» вы можете в документации.

Далее описываю содержание ответов для всех методов в объекте «responses». 

При проектировании API я разделяю ответ метода на 2 блока информации: «result» и «data». В объект “result” передаю технические метрики запроса. В массив “data” записываю значимые для конечного пользователя данные.

Для методов POST и PATCH, при успешном выполнении запроса, в “data” возвращается созданный/обновленный баннер.

Для метода GET, при успешном выполнении запроса, в “data” возвращается список баннеров, соответствующих заданным параметрам запроса.

Все ответы блока “result” разделены по кодам ответа. Для примера, я описал следующие коды:

• 200 — запрос успешно выполнен
• 400 — ошибка ввода данных
• 404 — ресурс не найден

В случае ошибки (400, 404) в ответе возвращается объект “result” в котором описывается ошибка и пустой массив “data”.

Подробней про объект «responses» вы можете прочитать в документации.

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

Как убрать дублирование кода в swagger документе

На данном этапе у меня уже описаны основные разделы API документа. 

Готовый документ для текущего этапа выглядит так (файл выложен в github репозитории): swagger-doc.json.

Сейчас в документе много повторений: 

• Для всех методов одинаково описывается блок информации об ошибках выполнения запроса. 
• Для методов post и patch доступны одинаковые параметры создания/обновления баннера. 
• Для всех методов при успешном выполнении запроса возвращается объект “result”
• В объекте “data”, при успешном выполнении запроса, для всех методов возвращается один или несколько баннеров с одинаковым набором атрибутов.

Давайте избавимся от дублирования данных. 

Повторяющиеся блоки информации описываются в объект «schemas», который вложен в объект «components». 

Везде, где необходимо использовать повторяющиеся блоки, указываются ссылки на нужные компоненты. 

Ссылка на схему выглядит так:

«$ref»: «#/components/schemas/{Название компонента}»

Объявление схемы:

"components": {
    "schemas": {
        "Название компонента": {
	      <описание параметров>
  }
    }
}

На примере информации об ошибках (картинка ниже) видно, что в Swagger UI ответ для кода 404, в котором я ссылаюсь на объект «ApiError», выглядит также как ответ для кода 400, в котором параметры ответа описаны внутри самого блока ошибки.

Преимущества, которые появляются, если корректно формировать объект «components»:

1. Скорость, экономия времени.
   Один раз описываешь нужный фрагмент кода в «components» и ссылаешься на него, где необходимо.
2. “Чистота” документации.
   При использовании такого подхода, документ легче читается и лучше выглядит. Значительно уменьшается количество строк.
3. Удобство изучения документации.
   Если нужно понять каков атрибутивный состав объектов или структуру запросов/ответов, удобней и быстрее – посмотреть нужную информацию в компонентах, а не разворачивать каждый из существующих в документе методов и искать данные там.

Подробней про объект «components» вы можете прочитать в документации.

После выделения повторяющихся блоков кода в раздел components/schemas, документ выглядит так (файл выложен в github репозитории): swagger-doc-2.json.

Краткое описание содержания Swagger документа

Формирование swagger документа из отдельных файлов

Если вести всю swagger документацию в одном файле, то он очень быстро разрастется до “нечитаемых” размеров. Для документации, содержащей множество методов и компонентов, имеет смысл использовать иной подход к организации swagger.

Разработчики обычно разделяют код на отдельные файлы, которые складываются в папки с разным уровнем вложенности. Итоговый код собирается как конструктор из ссылок на отдельные фрагменты. Так код легче читается, пишется и дорабатывается в перспективе. Со swagger документом тоже можно так делать. Чуть выше мы выделили повторяющиеся блоки: Banner, Result, ApiError, RequestBody. Далее я покажу как вынести их в отдельные файлы.

Как собрать swagger документ из отдельных файлов

Когда я начал “нарезать” документ на отдельный файлы, столкнулся с тем, что JSON очень требователен к разметке документа. Приходится больше тратить времени на отладку. Упростил себе жизнь и преобразовал ранее созданный файл (swagger-doc-2.json) из формата .json в формат .yaml с помощью https://editor.swagger.io/. В результате я получил файл (выложен в github репозитории): swagger-doc.yaml (здесь можно видеть, как файл выглядит до его разделения на компоненты).

Следующим шагом из файла “swagger-doc.yaml” вырезал в отдельные файлы все компоненты документации из раздела components/schemas и разложил их по заранее созданным папкам.

Остается в основном файле “swagger-doc.yaml” прописать корректно ссылки-пути на подключение нужных файлов.

Образец документации разделенной на  отдельные файлы (выложен в github репозитории): Banner.zip

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

Как использовать swagger в рабочей документации

Мне известно несколько способов публикации swagger документации для общего доступа:

1. Аналитик может самостоятельно сформировать swagger документ и добавить его к рабочей документации в Confluence используя стандартный макрос. Подробнее об этом чуть ниже в статье.
2. Аналитик может самостоятельно сформировать swagger документ и опубликовать его “как сайт” в сети указав ссылку на ресурс в рабочей документации.
3. Разработчик может сформировать swagger документ из рабочего проекта с помощью специальных библиотеки и опубликовать проект в сети самостоятельно.
4. Разработчик может сформировать swagger документ из рабочего проекта и предоставить аналитику итоговые данные в виде текстового файла, аналогичного тому, который аналитик формирует вручную.

Как в Confluence добавить Swagger документ

1. Открываю в режиме редактирования страницу в Confluence.
2. На панели редактирования документа нажимаю на иконку “Вставить прочий контент”.
3. Внизу выпадающего списка выбираю пункт “Другие макросы”.
4. В поле поиска пишу swagger и выбираю макрос “Open API (Swagger) Integration for Confluence
5. В окне настроек ничего не указываю и добавляю макрос с параметрами по умолчанию
6. После добавления макроса на страницу, появится пустая форма для ввода текста.
7. В форму вставляю весь подготовленный ранее код из редактора VS Code.
8. Сохраняю документ или нажимаю “Предпросмотр”
9. Готово. Теперь в проектной документации в Confluence можно видеть реализацию API и при необходимость вызывать/тестировать методы.

Как самостоятельно опубликовать swagger документацию в сети интернет

1. Перехожу в публичный github репозитория swagger-ui 
2. Скачиваю весь проект себе на компьютер

6. Далее остается все содержимое папки с проектом опубликовать на одном из многих хостингов. Как самый простой и бесплатный вариант, я опубликовал свое проект на GitHub Pages. Информацию о том, “как опубликовать проект на GitHub Pages” вы можете найти в сети во многих источниках. Документация: https://pages.github.com/

Ветка github репозитория из которой формируется GitHub Pages: swagger-ui-banners

Готовый проект вы можете увидеть по ссылке: https://ovchinin.github.io/banners-api/

Как разработчику сформировать swagger документацию и, при необходимости, опубликовать её в сети

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

Разработчик может сформировать swagger документацию используя различные библиотеки и плагины, например “Springdoc”.

Библиотека Springdoc позволяет автоматически генерировать документацию API в спецификации OpenAPI 3.0 из исходного кода приложения, используя аннотации из библиотеки Spring и Spring Boot. 

Вот что необходимо для того, чтобы начать использовать библиотеку: 

Для использования библиотеки Springdoc необходимо выполнить следующие шаги:

1. Добавьте зависимость на библиотеку Springdoc в файле pom.xml (если вы используете Maven) или build.gradle (если вы используете Gradle):

<dependency>
    <groupId>org.springdoc</groupId>
    <artifactId>springdoc-openapi-ui</artifactId>
    <version>1.5.9</version>
</dependency>

2. Добавьте аннотацию @EnableOpenApi в класс, который инициализирует ваше приложение Spring Boot:

@SpringBootApplication
@EnableOpenApi
public class MyApplication {
    public static void main(String[] args) {
        SpringApplication.run(MyApplication.class, args);
    }
}

3. Используйте аннотации из библиотеки Springdoc для описания ваших контроллеров и методов. Например:

@RestController
@RequestMapping("/api")
public class MyController {
    
    @Operation(summary = "Get a list of all items")
    @GetMapping("/items")
    public List<Item> getAllItems() {
        // ...
    }
    
    @Operation(summary = "Create a new item")
    @PostMapping("/items")
    public Item createItem(@RequestBody Item newItem) {
        // ...
    }
    
    // ...
}

Аннотация @Operation используется для описания каждого метода, аннотация @RequestBody указывает на то, что аргумент метода должен быть преобразован из тела запроса HTTP, и т.д.

После запуска приложения API документация будет доступна по ссылке http://localhost:8080/swagger-ui.html

Подробнее про данную библиотеку написано на официальном сайте: https://springdoc.org/

Если вы – разработчик и у вас есть что добавить, ждем в комментариях. 

Заключение 

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

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

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