# Соннет: проверь наш анализ 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 правок с максимальным эффектом при минимуме кода**.