1. Анализ предметной области

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

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

Основные проблемы, связанные с документированием веб-сервисов:

– несоответствие документации реализации;

– высокая трудоёмкость ручного сопровождения;

– ошибки, обусловленные человеческим фактором;

– отсутствие документации для унаследованных систем.

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

2. Обзор существующих решений

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

– инструменты ручного документирования;

– инструменты генерации документации из кода;

– инструменты анализа сетевого трафика.

К наиболее распространённым решениям относятся Swagger, Postman, ApiDog и Optic. Анализ показал, что существующие инструменты имеют следующие ограничения:

– необходимость ручного ввода данных;

– зависимость от исходного кода;

– сложность внедрения;

– ограниченная автоматизация;

– зависимость от облачных сервисов.

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

3. Концептуальная модель

На основе анализа предметной области и функциональных требований разработана концептуальная модель программного модуля для автоматизации документирования веб-сервисов (ПМ АДВС). Для визуализации границ системы и сценариев взаимодействия с внешним окружением использована диаграмма вариантов использования (Use Case Diagram) языка моделирования UML.

Оператор (Разработчик) — пользователь системы, который инициирует процесс работы модуля, настраивает параметры проксирования, управляет сессией записи и получает итоговый результат в виде файла спецификации в формате OpenAPI.

Концептуальная модель ПМ АДВС включает следующие ключевые сценарии:

– запуск прокси-сервера — оператор задает конфигурацию, включая локальный порт для прослушивания и адрес целевого хоста;

– просмотр статистики и логов — оператор может в реальном времени отслеживать журнал перехваченных запросов через графический интерфейс для контроля корректности работы системы;

– генерация файла спецификации — завершающий этап автоматического цикла, на котором на основе данных структурного анализа формируются объекты схемы OpenAPI и выгружаются в виде стандартизированного файла (JSON/YAML) для дальнейшего использования;

– остановка прокси-сервера.

Проиллюстрируем это на рис. 1.

Рис. 1. Концептуальная модель ПМ АДВС

4. Стек технологий

В стек используемых технологий для разработки программного модуля автоматического документирования веб-сервисов (ПМ АДВС) включены современные инструменты и библиотеки, обеспечивающие корректную обработку HTTP-трафика, работу с динамическими структурами данных, автоматизацию тестирования и поддержку качества кода. Подробнее про каждый из компонентов:

– язык программирования Python версии 3.11;

– асинхронный HTTP-фреймворк aiohttp;

– библиотека валидации данных Pydantic;

– управление переменными окружения python-dotenv;

– фреймворк для тестирования Pytest;

– фреймворк для создания CLI Typer;

– HTML, CSS, JavaScript: технологии для создания веб-интерфейса;

– WebSocket: протокол, который я использую для передачи логов с сервера на клиент в режиме реального времени.

5. Алгоритмы функционирования

Работа сервиса начинается с инициализации и запуска HTTP-сервера по адресу http://localhost:9001. После запуска сервер переходит в режим ожидания входящих запросов от клиентов. В зависимости от типа запроса возможны три сценария:

– запрос на получение пользовательского интерфейса (сервер отдаёт статические файлы и возвращается к ожиданию);

– REST API запрос (сервер принимает данные, выполняет валидацию, при корректности — обрабатывает запрос и отправляет JSON-ответ);

– установка WebSocket-соединения (сервер регистрирует клиента, контролирует состояние соединения и организует обмен сообщениями).

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

Схема алгоритма работы ПМ АДВС представлена на рис. 3.

Рис. 3. Схема алгоритма работы ПМ АДВС

Блок “Выполнение команды” подробнее рассмотрен на рис. 4.

Рис. 4. Выполнение команды

Далее внимание уделяется алгоритмам генерации схем данных, слияния схем данных, агрегации информации, выявления параметров в URL.

Реализация указанных алгоритмов представлена в открытом репозитории на платформе GitHub: https://github.com/ilyshks/apiscribe .

5.1 Генерация схем данных

Алгоритм генерации схем данных (реализован в Analyzer.generate_schema, файл analyzer.py) преобразует произвольное JSON-значение в JSON Schema:

– определяет тип данных через функцию isinstance;

– рекурсивно строит схему для объектов и массивов.

5.2 Слияние схем данных

Слияние элементов массива через merge_schema позволяет корректно обобщать разнородные типы внутри одного массива (например, [1, «str»] → items: {type: [«integer», «string»]}).

5.3 Агрегация информации

Алгоритм накапливает статистику по каждому уникальному кортежу (method, path) в хранилище InMemoryStorage. При обработке эндпоинта система извлекает поля запроса, создаёт модель EndpointModel и обновляет схему запроса через слияние существующих и новых данных.

5.4 Выявление параметров в URL (кластеризация + шаблонизация)

Пути кластеризуются по числу сегментов (path_cluster.py), затем анализируются посегментно (path_inference.py):

– одинаковые значения сегмента → константа;

– ≤3 значений и не все целые → первый сегмент как константа;

– целые числа → {prev}_id (integer);

– UUID → {prev}_uuid (string, format=uuid);

– остальное → {prev}_param (string).

Результат: шаблон пути и параметры в формате OpenAPI (имя параметра из предыдущего константного сегмента или «param»).

6. Результаты

Программный модуль автоматизирует создание актуальной документации (включая поддержку унаследованных систем) без привязки к исходному коду. Экспериментально подтверждена эффективность обработки сетевого трафика и формирования спецификаций.

Перспективы: расширение функционала, повышение точности анализа, интеграция с инструментами разработки.

Литература:

1. JSON Schema Specification. Draft 2020‑12. — URL: https://json-schema.org/draft/2020–12/json-schema-core
2. OpenAPI Specification (OAS), версия 3.1.0. — URL: https://spec.openapis.org/oas/v3.1.0.html
3. Язык программирования Python. — URL: https://www.python.org/doc/
4. Richardson, L., Ruby, S., Taylor, J. RESTful Web API. — O’Reilly Media, 2013. — 400 с.
5. Newcomer, E., Lomow, G. Understanding SOA with Web Services. — Addison-Wesley Professional, 2004. — 528 с.