Как программы договариваются друг с другом?

REST API, OpenAPI и Swagger UI на примере службы доставки.

Один сервис. Разные клиенты. Общие правила обмена.

Клиенты обращаются к одному Delivery API, который использует данные службы доставки

Одним API пользуются разные клиенты

Сайт, приложение, бот и Swagger UI обращаются к одной службе доставки.

Путь одного запроса

Клиент → HTTP-запрос → Delivery API → HTTP-ответ

GET /shipments/125 → данные о посылке № 125 в JSON

Swagger UI в этой цепочке — ещё один клиент.

Что фиксирует контракт API

Запрос

Метод, адрес, параметры, заголовки и тело.

Ответ

Статус, структура данных и типы полей.

Правила

Авторизация, ограничения и возможные ошибки.

HTTP-запрос: что отправляет клиент

GET /shipments/125 HTTP/1.1
Host: delivery.example.edu
Authorization: Bearer <token>
Accept: application/json

Где здесь метод, адрес ресурса и подтверждение доступа?

Ресурсы и методы

Метод	Пример	Смысл
`GET`	`/shipments`	Получить список.
`GET`	`/shipments/125`	Получить одну посылку.
`POST`	`/shipments`	Создать посылку.
`PATCH`	`/shipments/125`	Изменить часть данных.
`POST`	`/shipments/125/cancel`	Выполнить действие «отменить».

JSON: число и строка различаются

{ "id": 125,   "weight_grams": 2500 }
{ "id": "125", "weight_grams": "2500" }

Для человека ответы похожи. Программа может ожидать именно числа.

HTTP-ответ: данные и результат операции

Статус	Что это означает в примере
`200`	Посылка найдена; данные в ответе.
`201`	Новая посылка создана.
`401`	Запрос не аутентифицирован.
`403`	Доступ к операции запрещён.
`404`	Такой посылки не нашли.
`500`	Сбой на стороне сервера.

Сервер ответил — ещё не значит, что операция удалась.

Токен связывает запрос с пользователем

Получить

Клиент проходит предусмотренный сервисом вход.

Передать

Authorization: Bearer <token> в заголовке запроса.

Проверить

Сервер определяет пользователя и разрешённые действия.

Четыре разных понятия

API

Работающий интерфейс сервера.

Контракт

Правила запросов, ответов и ошибок.

OpenAPI

Машиночитаемое описание HTTP API.

Swagger UI

Веб-клиент, который читает описание и выполняет запросы.

OpenAPI описывает операцию

openapi: 3.1.0
paths:
  /shipments:
    get:
      summary: Список посылок
      responses:
        '200':
          description: Список получен

Один и тот же документ можно открыть как /openapi.json и через Swagger UI.

Что делает Swagger UI

Читает OpenAPI → строит форму → отправляет HTTP-запрос → показывает ответ

Authorize · Try it out · Execute · статус и JSON

Видимая документация помогает, но правильность API проверяет реальный ответ.

Демонстрация: найти и отменить посылку

Получить тестовый токен и открыть Swagger UI.
Вызвать GET /shipments.
Найти получателя и прочитать id из JSON.
Вызвать POST /shipments/{id}/cancel.
Повторно запросить посылку и проверить статус.

Нужный id сначала неизвестен: его надо найти в ответе.

Что остаётся после лекции

Один HTTP API может обслуживать разные интерфейсы.

Контракт задаёт методы, данные, доступ и возможные исходы.

OpenAPI делает правила читаемыми для инструментов; Swagger UI позволяет проверить их запросом.

Следующий шаг — использовать тот же контракт для создания клиента и проверки его работы.

← → листать · F полный экран