diff --git a/polygon-docs/sonnet-swagger-analysis-verified.md b/polygon-docs/sonnet-swagger-analysis-verified.md deleted file mode 100644 index afd9a28..0000000 --- a/polygon-docs/sonnet-swagger-analysis-verified.md +++ /dev/null @@ -1,152 +0,0 @@ -# Соннет: проверь наш анализ Swagger/OpenAPI в Polygon - -> Адресат: Claude Sonnet 4.6 (новый чат) -> ⛔ ОТВЕТ — ТОЛЬКО В ЧАТ. Не редактировать файлы. -> ⛔ НЕ предлагать переписывать всё. Только точечные правки. - ---- - -## Контекст - -**Polygon** (v0.4.0) — эмулятор REST API облачной платформы Nubes. -Задеплоен на `polygon.pythonk8s.dev.nubes.ru`. 17 эндпоинтов, 37 сервисов. - -Swagger UI (`/swagger`) + OpenAPI 3.1.0 спека (`/api/v1/svc/openapi.json`). - -Основные файлы: -- `polygon/site/routes/openapi.py` — ~500 строк, динамическая спека -- `polygon/site/templates/swagger.html` — Swagger UI 5 с CDN -- `polygon/site/app.py` — Flask, 7 blueprint'ов -- `polygon/site/mock_state.py` — синглтон состояния -- `polygon/site/routes/mock_routes.py` — `_mock/*` эндпоинты -- `polygon/site/routes/run.py` — `POST /run` - -## Что мы уже нашли - -Ниже — наш анализ. Проверь каждую находку: подтверждаешь? Есть что добавить? Что-то упустили? - ---- - -### 🔴 Баг 1 (критичный): Глобальная Bearer-авторизация не реализована - -**Спека врёт.** В `openapi.py` глобально: -```json -"security": [{"bearerAuth": []}] -``` -Но в `app.py` **нет** `before_request` с проверкой `Authorization: Bearer`. -Единственная auth — в `mock_routes.py` через `@bp.before_request`, и та проверяет **`X-Mock-Auth`**, не `Authorization`. - -Более того, комментарий в `mock_routes.py:39` прямо врёт: -```python -# Примечание: app.before_request уже проверяет Authorization: Bearer; -``` -Такого `before_request` не существует. - -**Последствия**: пользователь в Swagger UI нажимает Authorize, вводит токен, убеждён что защищён. На деле токен нигде не проверяется. `_mock/*` требует другой заголовок. - ---- - -### 🔴 Баг 2: dtStart, isSuccessful не nullable - -`mock_state.py` `create_operation()`: -```python -"dtStart": None, -"dtFinish": None, -"isSuccessful": None, -``` - -В схеме `Operation`: -- `dtFinish` — `"nullable": True` (но это синтаксис OAS 3.0, не 3.1.0) -- `dtStart` — без nullable -- `isSuccessful` — без nullable - -До `run` операция возвращает `{"dtStart": null, "dtFinish": null, "isSuccessful": null}`. Кодогенератор упадёт. - ---- - -### 🔴 Баг 3: RunResponse не включает поле error - -`run.py:73` при `fail_next`: -```python -return jsonify({"ok": False, "error": op["errorLog"]}) -``` - -Схема `RunResponse`: -```python -"RunResponse": {"type": "object", "properties": {"ok": {"type": "boolean"}}} -``` - -Поля `error` нет. - ---- - -### 🔴 Баг 4: pageSize — нет 400, тихое срезание - -Спека: `"maximum": 200` → подразумевает 400 при превышении. -Код `mock_state.py:72`: `page_size = min(page_size, 200)` — тихо срезает. - ---- - -### 🔴 Баг 5: nullable — синтаксис OAS 3.0 - -`"nullable": True` в `dtFinish` — валидно в OAS 3.0, но спека заявлена как **3.1.0**. В 3.1.0 нужно: `"type": ["string", "null"]`. - ---- - -### 🟡 Удобство 1: Нет описания lifecycle операций - -Пользователь видит 5 эндпоинтов в теге "operations" и не понимает порядок: -1. `GET /default/{svcOperationId}` -2. `POST /instanceOperations` -3. `POST /instanceOperationCfsParams` × N -4. `GET /{opUid}/validate-cfs` -5. `POST /{opUid}/run` - ---- - -### 🟡 Удобство 2: fields — нет enum и примера - -Описан как `"cs-список полей"` — пользователь не знает что писать в Try it out. - ---- - -### 🟡 Удобство 3: status/kind/action без enum - -`status: "creating | running | modifying | deleting | suspended"` — только в description. Try it out не подсказывает. - ---- - -### 🟡 Удобство 4: _mock/* смешаны с production - -Тег "mock" наравне с services/instances. Новичок не отличает тестовые эндпоинты от рабочих. - ---- - -### 🟡 Удобство 5: displayName — нет default - -Реально `body.get("displayName", "unnamed")`. В спеке default не указан. - ---- - -### 🔵 Косметика - -1. `bearerFormat: "token"` → нестандартное значение -2. `ServiceDetail` схема обрывается (operations описаны частично) -3. Тег "health" не нужен пользователям в документации -4. Нет `example` в схемах (Instance, CfsParam, Operation) - ---- - -## Что от тебя нужно - -1. **Подтверди или оспорь** каждую находку -2. **Что мы пропустили?** — есть баги/неудобства которые мы не заметили? -3. **Приоритеты** — что чинить в первую очередь? -4. **Best practices** — как ПРАВИЛЬНО сделать, чтобы Swagger был «кошерным»: - - Группировка тегов - - Описание схем для Try it out - - Скрытие служебных эндпоинтов - - Русские summary/description - - Авторизация в Swagger UI - -В конце — **3-5 правок с максимальным эффектом при минимуме кода**.