docs: clarify Polygon auth and API contracts

site/routes/instances_routes.py

@@ -71,7 +71,7 @@ def create_instance():
     Также возвращает {"instanceUid": uid} в теле — двойная защита
     на случай если заголовок не дойдёт.
     """
-    body = request.get_json(silent=True) or {}
+    body = request.get_json(silent=True)
 
     # ⛔ body должен быть dict, не массив и не примитив
     if not isinstance(body, dict):

site/routes/openapi.py

@@ -82,7 +82,11 @@ def _build_spec():
                 "### Авторизация\n"
                 "- Основные эндпоинты — без авторизации\n"
                 "- `_mock/*` требуют заголовок `X-Mock-Auth`, только если на сервере "
-                "задан `MOCK_AUTH_TOKEN`"
+                "задан `MOCK_AUTH_TOKEN`. Администратор задаёт его в переменных "
+                "окружения сервиса; Swagger не может получить это значение с сервера.\n"
+                "- В Swagger нажмите **Authorize**, вставьте токен в поле `X-Mock-Auth` "
+                "и нажмите **Authorize** в диалоге. Для curl передавайте "
+                "`-H \"X-Mock-Auth: <token>\"`. Если токен не настроен, заголовок не нужен."
             ),
             "contact": {
                 "name": "Nubes Platform",
@@ -104,7 +108,11 @@ def _build_spec():
                     "type": "apiKey",
                     "in": "header",
                     "name": "X-Mock-Auth",
-                    "description": "Нужен для _mock/* только если MOCK_AUTH_TOKEN задан на сервере.",
+                    "description": (
+                        "Если MOCK_AUTH_TOKEN задан администратором сервиса, введите его "
+                        "в поле Value и нажмите Authorize. Значение берётся из конфигурации "
+                        "окружения сервера; Swagger его не показывает."
+                    ),
                 },
             },
             "schemas": {
@@ -553,7 +561,10 @@ def _build_paths():
                         "content": {"application/json": {"schema": {"$ref": "#/components/schemas/CreateOperationResponse"}}},
                     },
                     "400": {
-                        "description": "instanceUid обязателен",
+                        "description": (
+                            "Некорректный JSON или тип поля, отсутствует обязательное поле, "
+                            "либо operation не соответствует svcOperationId"
+                        ),
                         "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}},
                     },
                     "404": {
@@ -696,7 +707,12 @@ def _build_paths():
                 },
                 "responses": {
                     "200": {
-                        "description": "Параметр установлен (пустое тело)",
+                        "description": "Параметр установлен",
+                        "content": {
+                            "application/json": {
+                                "schema": {"type": "object", "example": {}},
+                            },
+                        },
                     },
                     "400": {
                         "description": "Не указан instanceOperationUid или svcOperationCfsParamId",
@@ -706,6 +722,10 @@ def _build_paths():
                         "description": "Операция не найдена",
                         "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}},
                     },
+                    "409": {
+                        "description": "Операция уже завершена",
+                        "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}},
+                    },
                 },
             },
         },

site/routes/operations_routes.py

@@ -169,12 +169,16 @@ def create_operation():
     )
     if target_op is None:
         return jsonify({"error": f"operation '{operation}' not found for service"}), 404
+    if target_op.get("operation") != operation:
+        return jsonify({"error": "operation does not match svcOperationId"}), 400
 
     kind = target_op.get("kind", "instance")
     action = target_op.get("action", operation)
 
     # Создать операцию в MockState (dtFinish=None — ещё не выполнена)
-    op_uid = state.create_operation(instance_uid, svc_op_id, operation, kind, action)
+    op_uid = state.create_operation(
+        instance_uid, svc_op_id, target_op["operation"], kind, action
+    )
 
     # ⛔ Location ОБЯЗАТЕЛЕН — без него executor не получит opUid
     resp = make_response(jsonify({"instanceOperationUid": op_uid}), 201)

site/routes/root.py

@@ -78,6 +78,7 @@ def index():
         svc_list=svc_list,
         stands_list=stands_list,
         current_stand=current_stand,
+        swagger_url=(f"/{current_stand}/swagger" if len(stands_list) > 1 else "/swagger"),
         endpoint=_POLYGON_ENDPOINT,
     )
 
@@ -92,8 +93,10 @@ def swagger():
     from routes.openapi import _build_spec
     import json as _json
     spec_json = _json.dumps(_build_spec(), ensure_ascii=False)
+    home_url = f"/{g.stand_id}/" if len(_cfg.list_stands()) > 1 else "/"
     return render_template(
         "swagger.html",
         version=_cfg.VERSION,
         spec_json=spec_json,
+        home_url=home_url,
     )