Анализ данных • 27 октября 2023 • 5 мин чтения

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

Задача системного аналитика — формировать требования к разрабатываемым IT-системам. Swagger — один из инструментов, который помогает это делать и контролировать их выполнение.

Что такое Swagger и при чем здесь REST API

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

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

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

Вот пример части документации, составленной с использованием Swagger:

openapi: 3.0.0
info:
title: Example API Documentation
version: 1.0.0
description: This is an example API documentation for a sample application.

paths:
/users:
get:
summary: Get a list of users
operationId: getUsers
description: Retrieves a list of all users in the system.
responses:
'200':
description: A list of users
content:
application/json:
schema:
$ref: '#/components/schemas/UsersList'

components:
schemas:
UsersList:
type: array
items:
type: object
properties:
id:
type: integer
description: The user's ID
name:
type: string
description: The user's name

В этом примере показана часть документации для одного из ресурсов — "/users". Метод "GET" позволяет получить список пользователей.

Документация содержит следующую информацию:

● Заголовок с названием и версией API и описание
● Описание ресурса с описанием операции
● Ответ, который будет возвращаться при успешном выполнении операции, с указанием ожидаемого формата (application/json) и модели данных (UsersList)
● Компоненты, где определена модель данных "UsersList", которая представляет собой массив объектов с полями "id" и "name"

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

Работа с Rest API — один из навыков, которые студенты получают на курсе «Системный аналитик». Они учатся проектировать и описывать взаимодействие систем, в том числе с использованием Swagger.

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

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

Разработчики API

● Документация. Swagger позволяет автоматически создавать документацию для API на основе спецификации OpenAPI. Это включает в себя информацию о доступных методах, параметрах, типах данных и возвращаемых значениях.
● Проверка совместимости. Swagger позволяет проверять совместимость API до его реализации, путем создания и валидации спецификации. Это позволяет обнаружить и исправить потенциальные проблемы дизайна и конфигурации API ещё до его запуска.
● Генерация клиентского кода. Swagger позволяет автоматически генерировать клиентский код для различных языков программирования на основе спецификации OpenAPI. Это позволяет разработчикам быстро интегрировать API в свои приложения без необходимости вручную создавать и настраивать HTTP-запросы.
● Продвижение API. Swagger предоставляет интерактивную документацию, которая может быть использована для рекламы и продвижения API. Разработчикам будет легко понять, как использовать API, а также его функциональность и возможности.
● Улучшение командной работы. Swagger предоставляет единый и точный источник информации об API. Спецификация OpenAPI — стандартная форма описания API, которую может использовать вся команда для понимания функциональности и взаимодействия с API.

Системные аналитики

● Описание и проектирование API. Swagger позволяет системному аналитику создать спецификацию API, которая описывает структуру, параметры и операции, предлагаемые API. Это позволяет аналитику получить чёткое представление о функциональности API и понять, как оно взаимодействует с другими компонентами системы.
● Согласование требований. Системный аналитик может использовать спецификацию API в Swagger для согласования требований с клиентами, разработчиками или другими заинтересованными сторонами. Swagger позволяет визуализировать функциональность API и обсудить её с заинтересованными сторонами, чтобы убедиться, что требования правильно поняты и соответствуют ожиданиям.
● Создание документации. Swagger предоставляет возможность автоматически генерировать интерактивную документацию для API. Системный аналитик может использовать Swagger для создания подробной документации, которая объясняет параметры, пути, операции и примеры использования API. Это помогает разработчикам и пользователям лучше понять и использовать API.
● Тестирование и отладка API. Swagger позволяет системному аналитику тестировать и отлаживать API, используя интерактивную консоль Swagger UI. Аналитик может отправлять запросы к API, проверять ответы и убедиться, что API работает корректно и соответствует требованиям.
● Взаимодействие с разработчиками. Swagger предоставляет спецификацию API в формате JSON или YAML, который можно передать разработчикам для создания клиентского кода или для интеграции с системами. Системный аналитик может использовать Swagger для обмена информацией с разработчиками, что повышает согласованность и эффективность в процессе разработки.

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

Существует несколько способов создания документации API с помощью Swagger:

1. Ручное создание YAML или JSON файлов спецификации.
Можно написать YAML или JSON файл спецификации OpenAPI вручную, описывая конечные точки (эндпойнты), параметры запросов, ответы и другие свойства API. Это требует знания синтаксиса и структуры спецификации, но даёт полный контроль над создаваемой документацией.

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

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

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

3. Интеграция с инструментами автоматической генерации документации.
Существуют инструменты, которые могут извлекать информацию об API из кода и автоматически создавать документацию Swagger. Например, Swagger JSDoc для JavaScript, Swagger-php для PHP и другие инструменты для различных языков программирования.

Компонента Swagger

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

Компоненты в Swagger описываются в разделе "components" файлов спецификации OpenAPI. Внутри раздела "components" можно определить различные типы компонентов, такие как схемы (schemas), параметры (parameters), запросы (request bodies), ответы (responses), заголовки (headers) и другие.

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

Пример использования компонентов в спецификации OpenAPI выглядит так:

components:
schemas: # компоненты схем
User: # имя схемы
type: object
properties:
id:
type: integer
name:
type: string

parameters: # компоненты параметров
userId: # имя параметра
name: user_id
in: path
required: true
schema:
type: integer
format: int64

paths:
/users/{userId}/posts:
get:
parameters:
- $ref: '#/components/parameters/userId' # использование компонента параметра
responses:
200:
description: Success
content:
application/json:
schema:
$ref: '#/components/schemas/User' # использование компонента схемы

Компоненты в OpenAPI позволяют создавать модульную и удобную для использования спецификацию API, повышая повторную используемость и сокращая дублирование кода и документации.

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

✅Преимущества

1. Стандартная спецификация API. OpenAPI — это открытый стандарт для описания RESTful API. Его использование обеспечивает единообразие и стандартизацию документации API, что упрощает её понимание и использование для разработчиков и пользователей API.
2. Автоматическая генерация документации. Swagger позволяет автоматически сгенерировать документацию API на основе спецификации. Это значительно экономит время и усилия разработчиков, которым больше не нужно создавать документацию вручную.
3. Интерактивная документация и средства отладки. Swagger предоставляет интерактивную документацию API, которая позволяет пользователям протестировать запросы и просмотреть ответы непосредственно в интерфейсе Swagger UI или инструменте Swagger UI. Это упрощает отладку и тестирование API.
4. Генерация клиентского кода. Swagger позволяет автоматически сгенерировать клиентский код для различных языков программирования на основе спецификации API. Это облегчает интеграцию с API и ускоряет разработку клиентских приложений.
5. Лёгкая поддержка при изменении API. Если API изменяется, достаточно обновить спецификацию Swagger, и документация, клиентский код и другие артефакты будут автоматически обновлены.

❌Недостатки

1. Обучение и адаптация. Использование Swagger требует знания синтаксиса и структуры спецификации OpenAPI. Новым специалистам может потребоваться время на освоение инструментов Swagger и изучение синтаксиса OpenAPI.
2. Ограничения спецификации. Несмотря на то, что OpenAPI предоставляет широкий набор возможностей для описания API, в некоторых случаях могут возникнуть ограничения или необходимость в применении специфических дополнений для описания более сложных сценариев или элементов API.
3. Зависимость от инструментов Swagger. Использование Swagger может потребовать использования специальных инструментов для генерации документации, кода и других артефактов. Это может создавать зависимость от этих инструментов и усложнять процесс, если требуется работа с другими инструментами или разработческими средами.
4. Риск несоответствия документации и реализации API. В случае, если спецификация API в Swagger не синхронизирована с фактической реализацией API, может возникнуть несоответствие или расхождение между документацией и поведением API.

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

Для начала работы со Swagger понадобится выполнить следующие шаги:

1. Установить Swagger.
Можно выбрать один из популярных инструментов Swagger, таких как Swagger UI, Swagger Editor или Swagger Codegen. Можно установить их локально на своём компьютере или использовать онлайн-редактор.
2. Определить спецификацию API.
Спецификация API — это документ, который описывает структуру и функциональные возможности API. Можно создать спецификацию API в формате YAML или JSON. Swagger предоставляет возможности для описания путей, параметров, моделей данных, операций и других компонентов API.
3. Отредактировать спецификацию API.
Используя инструмент Swagger Editor или любой другой, можно отредактировать спецификацию API в соответствии с изменяющимися требованиями проекта. Можно добавить пути, операции, параметры, модели данных и другие необходимые компоненты.
4. Генерировать документацию и клиентский код.
Используя инструмент Swagger, можно автоматически сгенерировать интерактивную документацию и клиентский код для API. Это упростит использование API для разработчиков и позволит им быстро интегрировать API в свои приложения.
5. Развернуть Swagger UI.
Если в проекте используется Swagger UI для отображения документации, лучше развернуть его на сервере или хостинге. Так документация будет доступна для разработчиков и пользователей API. Важно убедиться, что документация доступна по URL-адресу и имеет хорошо структурированный и понятный интерфейс.
6. Поддерживать и обновлять спецификацию API.
При изменении API важно обновлять спецификацию Swagger для отражения этих изменений и поддержания документации к системе в актуальном состоянии.

Совет эксперта

Юлия Кононенко

Swagger не нужно пытаться изучать в начале карьеры. Важно освоить подходы к проектированию API «на салфетке», а затем уже нанизывать уверенные навыки проектирования на удобные и полезные инструменты. Также очень важно не бояться осваивать новое. Ошибаться по пути не страшно, главное — практика и желание развиваться.

Статью подготовили: