121 lines
5.0 KiB
Markdown
121 lines
5.0 KiB
Markdown
# 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. |
|
||
|
||
---
|
||
|
||
## Требования к запуску
|
||
|
||
1. Репозиторий клонирован целиком (есть `tools/`, `server/`, `client/`).
|
||
2. Backend запускается из каталога **`server/`** (`npm run start` / `start:dev`), чтобы относительные пути `../tools/api-format-to-openapi/convert.mjs` были корректны.
|
||
3. Для режима 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`**
|
||
|
||
```http
|
||
Content-Type: application/json
|
||
X-AID-Export-Key: <если задан AID_EXPORT_API_KEY>
|
||
```
|
||
|
||
```json
|
||
{
|
||
"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
|
||
|
||
```bash
|
||
cd tools/api-format-to-openapi
|
||
node convert.mjs --in examples/api-format.example.json --out ../../openapi.generated.json
|
||
```
|
||
|
||
LLM:
|
||
|
||
```bash
|
||
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
|
||
|
||
1. AID уже сформировал **api-format** (как у вас принято после DTO).
|
||
2. 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.
|