docs: clarify Polygon auth and API contracts

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"}}},
+                    },
                 },
             },
         },