Лекция 4

1.

Спецификации OpenAPI и AsyncAPI
Описание интерфейсов хранения и
извлечения данных
Докладчик
Несмиянова Елена Сергеевна

2.

Фундамент современной интеграции подсистем хранения и извлечения данных
OpenAPI — для синхронных HTTP-интерфейсов - REST
AsyncAPI — для асинхронных событийно-ориентированных интерфейсов – Kafka, Rabbit
Оба стандарта решают одну и ту же задачу: дают машинночитаемое, формализованное описание того, как системы
обмениваются данными. Но делают это для принципиально
разных коммуникационных моделей.

3.

Зачем нужны спецификации API
Единый источник истины. Один файл (YAML или JSON)
описывает весь контракт API. Все команды работают с
ним, а не с разрозненными описаниями.
Генерация кода. На основе спецификации инструменты
автоматически создают клиентские SDK, серверные
заглушки (stubs), моки для тестирования.
Документация. Спецификация преобразуется в
интерактивную HTML-документацию, доступную как
разработчикам, так и техническим писателям.
Валидация. Инструменты могут проверять входящие и
исходящие сообщения на соответствие контракту,
используя JSON Schema.
Тестирование. Спецификация служит основой для
автотестов, контрактовых тестов и fuzzing-тестирования.

4.

OpenAPI Specification (OAS)
OpenAPI Specification (OAS) — это стандарт описания RESTful API
Swagger Specification
Текущая версия — OpenAPI 3.2.0, выпущенная 19 сентября
2025 года. Среди нововведений: иерархические теги,
нативная поддержка стриминговых медиа-типов,
поддержка произвольных HTTP-методов, OAuth2 device
flow и уточнённая семантика шаблонов путей.

5.

Эволюция версий

6.

Структура документа
Метаданные - info
openapi: 3.2.0
info:
title: Petstore API
version: 1.0.0
description: API для управления питомцами
Серверы - servers
servers:
- url: https://api.example.com/{basePath}
variables:
basePath:
default: /v1

7.

Пути и операции - paths
paths:
/pets:
get:
summary: Получить список питомцев
parameters:
- name: limit
in: query
required: false
schema:
type: integer
minimum: 1
maximum: 100
responses:
'200':
description: Список питомцев
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/Pet'

8.

securitySchemes
Модели данных – components/schemas
components:
schemas:
Pet:
type: object
required: [id, name]
properties:
id:
type: integer
name:
type: string
status:
type: string
enum: [available, pending, sold]
Безопасность - sucuritySchemes

9.

Посмотрим полноценный код

10.

AsyncAPI Specification
Канал (channel) — механизм маршрутизации сообщений. В
Kafka это topic, в RabbitMQ — exchange или queue, в
WebSocket — именованный канал.
Операция (operation) — действие приложения: отправка сообщения в канал
или приём сообщения из канала. Важно: это действия приложения, а не
сервера.
Сообщение (message) — единица обмена данными,
содержащая полезную нагрузку (payload), заголовки и
метаданные.
Сервер (server) — брокер сообщений или WebSocketсервер, к которому подключается приложение.

11.

Поддерживаемые протоколы
•Kafka — распределённый лог событий
•AMQP (RabbitMQ) — брокер очередей
•MQTT — лёгкий протокол для IoT
•WebSocket — двунаправленная связь поверх HTTP
•HTTP — для polling-сценариев
•NATS, Solace, Google Pub/Sub, JMS и другие

12.

Посмотрим полноценный код

13.

Сравнение OpenAPI и AsyncAPI

14.

Где используется OpenAPI
• REST API доступа к данным — CRUD-операции над записями, поисковые
запросы, пагинация.
• Управляющие API — создание и конфигурация хранилищ, управление
индексами, управление пользователями.
• Интеграционные шлюзы — API-гейтвеи (Kong, API Connect),
маршрутизирующие запросы к backend-сервисам хранения.
• Контрактное тестирование — проверка, что реализация соответствует
описанию.

15.

Где используется AsyncAPI
• Потоковая обработка данных — конвейеры Kafka, где события поступают в
топики и обрабатываются консьюмерами.
• IoT-системы — телеметрия с датчиков по MQTT, команды исполнительным
устройствам.
• Системы реального времени — уведомления, чаты, стриминговые
платформы через WebSocket.
• Change Data Capture (CDC) — события об изменениях в базе данных,
публикуемые в брокер сообщений.
• Интеграция корпоративных систем — единое описание всех точек
интеграции между разнородными подсистемами через event bus.