OpenAPI-схема
Машиночитаемый контракт /v1/process — откуда взять схему, как сгенерировать типизированный клиент и почему справочник живет прямо здесь.
Справочник REST на этом сайте генерируется из схемы OpenAPI — той же, что описывает контракт в коде сервиса. Отдельного Swagger UI на стороне API для чтения документации больше не нужно: страницы операций, схемы запроса и ответа и песочница «попробовать» живут внутри этой документации, в одной оболочке с остальными разделами.
Взять схему
curl -o docinspect-openapi.json https://ai.docinspect.ru/openapi.jsonИз нее генерируется типизированный клиент любым стандартным генератором:
npx openapi-typescript docinspect-openapi.json -o src/docinspect.d.tsАвторизация везде одна и та же — заголовок X-API-Key, см.
«Аутентификация».
Что в схеме, а чего в ней нет
Обработка документов — это POST /v1/process и поллинг
GET /v1/process/{task_id}; обе операции разобраны в
Справочнике REST. Остальное в живой схеме —
служебные контуры (проверка состояния, статистика, управление клиентами) и
эндпоинты прошлых итераций API, которые доживают до миграции внутренних
потребителей и новым интеграциям не предназначены. Справочник на сайте
собирается из отфильтрованной копии схемы, поэтому в нем только то, на что
можно опираться.
Схема — форма, а не смысл
OpenAPI отвечает, какие поля бывают и каких они типов. Почему result
иногда приходит null, чем prompt отличается от чистой схемы и что
делать с warnings[] — это «/v1/process»,
«output_schema» и «Ошибки».