Swagger и маршрутизация

Swagger UI

Каждый микросервис AI Server предоставляет собственную документацию Swagger (OpenAPI) со списком всех доступных эндпоинтов, моделей данных и возможностью отправлять тестовые запросы.

Адреса Swagger UI

Swagger UI каждого сервиса доступен по пути /api/doc относительно корня этого сервиса.

Авторизация в Swagger

Swagger UI поддерживает авторизацию через JWT-токен. Нажмите кнопку Authorize в интерфейсе Swagger и вставьте токен (без префикса Bearer). После этого все запросы из Swagger будут автоматически включать заголовок Authorization.

Получение токена описано в разделе Авторизация.

Маршрутизация через Nginx

Все сервисы AI Server доступны через единую точку входа — Nginx на порту 44392 (HTTPS). Nginx терминирует TLS и маршрутизирует запросы по префиксу URL:

Nginx снимает префикс и подставляет /api/. Например, запрос https://<host>:44392/inference/nlp/ready превращается в http://server_inference:5012/api/nlp/ready.

Swagger через Nginx — ограничения #swagger-nginx

Все микросервисы внутри используют маршруты, начинающиеся с /api/.... Когда Swagger UI отображает эндпоинт, он показывает его внутренний путь — например, POST /api/nlp/{modelType}/async для сервиса Api.Inference.

При отправке запроса Swagger использует именно этот путь. Nginx получает запрос на /api/nlp/{modelType}/async и маршрутизирует его в сервис Api (порт 5556), а не в Api.Inference (порт 5012). Запрос попадает не в тот сервис и завершается ошибкой.

Аналогичная ситуация с сервисом Api.Auth — его эндпоинты начинаются с /api/, но через Nginx должны вызываться с префиксом /auth/.

Прямой доступ к сервисам #direct-access

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

Открытие портов в Docker Compose #docker-ports

По умолчанию внутренние порты сервисов не проброшены наружу — единственный открытый порт это 44392 (Nginx). Чтобы получить прямой доступ к Swagger UI, нужно открыть порт нужного сервиса в файле docker-compose.yaml.

Найдите секцию нужного сервиса и раскомментируйте строку ports, указав IP-адрес машины, с которой планируете обращаться:

# Было (порт закрыт):
  Inference:
    ...
    #ports:
    #  - 5012:5012
 
# Стало (порт открыт для конкретного IP):
  Inference:
    ...
    ports:
      - 10.83.10.50:5012:5012

Где 10.83.10.50 — IP-адрес машины, которой разрешён доступ. Это ограничивает прослушивание порта только указанным интерфейсом. Если нужен доступ с любого адреса, используйте 0.0.0.0:5012:5012, но только в изолированной сети.

Порты сервисов:

После изменения перезапустите контейнеры:

docker compose up -d