Руководство · Стандарт или спецификация

OpenAPI как машиночитаемое описание действий

Как OpenAPI помогает программам и агентам понять HTTP API, какие части контракта важны для безопасного вызова и почему опубликованная схема не заменяет серверные правила авторизации.

Опубликовано: 8 августа 2026
Обновлено: 13 августа 2026

Ограничение: материал объясняет проверяемый технический сигнал. Его наличие не гарантирует ранжирование, индексацию, цитирование или включение сайта в ответы ИИ.

Что описывает OpenAPI

OpenAPI Specification задаёт независимое от языка программирования описание HTTP API: пути, операции, параметры, схемы запросов и ответов, серверы и схемы безопасности. Такой документ позволяет программному клиенту понять интерфейс без чтения исходного кода.

Для сценариев с ИИ-агентами это удобный слой описания возможностей, но он не превращает каждую описанную операцию в безопасный инструмент. Машиночитаемость контракта и право выполнить действие — разные свойства.

Что проверяет AI Web Check

В AI-commerce сервис показывает наличие OpenAPI как отдельный необязательный сигнал. Анализ ограничен уже объявленной публичной метаинформацией и не запускает описанные операции.

AI Web Check не следует внешним `$ref` без необходимости, не отправляет учётные данные для авторизации и не пытается «проверить» checkout реальным заказом. Цель — определить, есть ли понятный машиночитаемое описание API и безопасно ли объявлены endpoint.

Минимально полезный контракт

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

openapi: 3.1.0
info:
  title: Catalog API
  version: 1.0.0
paths:
  /products:
    get:
      summary: List public products
      responses:
        '200':
          description: Product list

Типичные ошибки

Документ OpenAPI расходится с рабочим API.
Схема безопасности отсутствует у операции, которая меняет данные.
URL сервера содержит учётные данные, localhost или внутреннее имя хоста.
Описание операции не говорит о побочных эффектах, идемпотентности или обязательном подтверждении.

Как сделать контракт понятным для агента

Давайте операциям однозначные summary и operationId, используйте строгие схемы, перечисляйте реальные коды ошибок и явно задавайте требования безопасности. Разделяйте операции только для чтения и операции, изменяющие состояние.

Для опасных действий добавляйте серверные правила авторизации, учётные данные с минимальными полномочиями, механизмы идемпотентности и подтверждения, а также аудит. Никакой OpenAPI-файл сам по себе не обеспечивает эти свойства.