AID: экспорт OpenAPI и генератор приложения

В репозитории добавлены сервисы-экспортёры для интеграции с AID (или любым другим клиентом по HTTP): автоматическое получение OpenAPI 3.0 из доменного api-format.

Что работает

Компонент	Назначение
`POST /aid/export/openapi` (NestJS)	На вход JSON api-format → на выход документ OpenAPI 3.0 в поле `openapi`.
`tools/api-format-to-openapi/`	CLI и промпт для LLM: тот же конвертер, что вызывает Nest.
`server/src/aid-export/`	Модуль Nest: контроллер, сервис, краткая справка в `README.md` рядом с кодом.

Что временно не работает

Компонент	Статус
`POST /aid/export/app` (DSL → бандл/apply)	Non-operative. The backing script (`generation/generate.mjs`) was removed during the architecture migration to api.dsl-first LLM generation. The endpoint returns 500 with a descriptive error.

Требования к запуску

Репозиторий клонирован целиком (есть tools/, server/, client/).
Backend запускается из каталога server/ (npm run start / start:dev), чтобы относительные пути ../tools/api-format-to-openapi/convert.mjs были корректны.
Для режима OpenAPI через LLM на сервере нужны OPENAI_API_KEY (и при необходимости OPENAI_MODEL, OPENAI_BASE_URL).

Переменные окружения (`server/.env`)

Переменная	Зачем
`AID_EXPORT_API_KEY`	Если задана, к *`/aid/export/` нужен заголовок `X-AID-Export-Key`** с тем же значением.
`OPENAI_API_KEY`	Для `POST /aid/export/openapi` с `"mode": "llm"`.

Остальное как для обычного бэкенда (DATABASE_URL, PORT и т.д.).

HTTP API (интеграция с AID)

Базовый URL: http://<host>:<port> (например http://localhost:3000).

1. OpenAPI из api-format

POST /aid/export/openapi

Content-Type: application/json
X-AID-Export-Key: <если задан AID_EXPORT_API_KEY>

{
  "apiFormat": {
    "apiFormatVersion": "1",
    "info": { "title": "API", "version": "1.0.0" },
    "server": { "basePath": "/api" },
    "resources": []
  },
  "mode": "deterministic"
}

mode: deterministic (по умолчанию) — маппинг в коде для схемы версии 1; llm — вызов OpenAI по промпту из tools/api-format-to-openapi/prompts/llm-system.md.

Ответ: { "openapi": { "openapi": "3.0.3", ... } }

Пример входа для теста: tools/api-format-to-openapi/examples/api-format.example.json (подставьте как значение apiFormat).

2. Генератор приложения из DSL (non-operative)

POST /aid/export/app

Non-operative. This endpoint depended on generation/generate.mjs which was removed during the migration to api.dsl-first LLM generation. It currently returns HTTP 500 with a descriptive error message. Restoring this endpoint requires implementing a new backing script compatible with the current domain/*.api.dsl pipeline.

CLI (без Nest)

api-format → OpenAPI

cd tools/api-format-to-openapi
node convert.mjs --in examples/api-format.example.json --out ../../openapi.generated.json

LLM:

set OPENAI_API_KEY=sk-...
node convert.mjs --mode llm --in your-api-format.json --out ../../openapi.llm.json

Подробнее: tools/api-format-to-openapi/README.md.

Типичный сценарий для AID

AID уже сформировал api-format (как у вас принято после DTO).
AID вызывает POST /aid/export/openapi → получает OpenAPI 3.0 → сохраняет в проект / отдаёт в Swagger / в реестр.

Где смотреть код и короткую справку

Полное описание эндпоинтов рядом с реализацией: server/src/aid-export/README.md

Ограничения и дальнейшие шаги

Пример api-format в репозитории — учебный; под ваш продакшен-формат может понадобиться расширить маппинг в convert.mjs или отточить промпт llm-system.md.
/aid/export/app requires a new backing implementation compatible with the domain/*.api.dsl pipeline to be restored. See docs/future-work.md for planned future work.

5.0 KiB Raw Permalink Blame History Unescape Escape