fix(docs,security): Swagger UI — staging для exploration, prod env-flagged

docs/index.md

@@ -67,11 +67,15 @@
 
 - Я хочу пощупать API
 
-  Открой [Swagger UI](https://ordinis.k8s.264.nstart.cloud/swagger-ui.html) —
+  Открой [Swagger UI на staging](https://ordinis.k8s.265.nstart.cloud/swagger-ui.html) —
   там можно нажать **Authorize** → войти через Keycloak (PKCE, без secret) →
   и сразу делать «Try it out» с реальным JWT. Authorization, error codes,
   schemas — всё через interactive UI.
 
+  **Важно:** прод (`/k8s.264.nstart.cloud/`) — для реальных пользователей,
+  не для exploration. Запросы там влияют на бизнес-данные. Используй
+  staging для изучения API.
+
 {% endlist %}
 
 ## Что нового в продукте

docs/integration/api/read-endpoints.md

@@ -14,13 +14,22 @@ Base URL:
 
 ## OpenAPI / Swagger UI
 
-Interactive playground с **Keycloak login** (PKCE flow, без client_secret):
+Interactive playground с **Keycloak login** (PKCE flow, без client_secret).
 
-- **Swagger UI:** `https://ordinis.k8s.264.nstart.cloud/swagger-ui.html`
+**Используй staging для exploration, не prod.** Прод — для реальных
+пользователей и боевых данных. Запросы из Swagger UI создают
+audit-записи и могут менять данные если ты случайно нажмёшь POST/PUT/DELETE.
+
+- **Swagger UI (staging):** `https://ordinis.k8s.265.nstart.cloud/swagger-ui.html`
   → нажми **Authorize** → выбери `oauth2` → войдёшь через Keycloak.
   После login каждый "Try it out" автоматически добавит JWT.
-- **Spec JSON:** `https://ordinis.k8s.264.nstart.cloud/v3/api-docs`
-- **Spec YAML:** `https://ordinis.k8s.264.nstart.cloud/v3/api-docs.yaml`
+- **Spec JSON (staging):** `https://ordinis.k8s.265.nstart.cloud/v3/api-docs`
+- **Spec YAML (staging):** `https://ordinis.k8s.265.nstart.cloud/v3/api-docs.yaml`
+
+OpenAPI spec для clients (SDK generation, code-first integration) можно
+также pull from prod (`/v3/api-docs` на k8s.264) — это статичный файл,
+безопасный для machine consumption. Для interactive exploration — только
+staging.
 
 {% note tip %}
 

ordinis-app/src/main/resources/application.yml

@@ -77,10 +77,18 @@ ordinis:
     attempt-max: ${ORDINIS_OUTBOX_ATTEMPT_MAX:1000}
 
 springdoc:
+  # Per env policy:
+  #   prod  → swagger UI disabled (real-user environment, не для exploration);
+  #           api-docs JSON остаётся для SDK generation / machine consumers
+  #   staging/dev → оба enabled (interactive playground для интеграторов)
+  # Controlled via ORDINIS_SWAGGER_UI_ENABLED env var (helm values-prod.yaml:
+  # springdoc.swaggerUi=false). Default true для backward compat.
   api-docs:
     path: /v3/api-docs
+    enabled: ${ORDINIS_SWAGGER_API_DOCS_ENABLED:true}
   swagger-ui:
     path: /swagger-ui.html
+    enabled: ${ORDINIS_SWAGGER_UI_ENABLED:true}
     operations-sorter: method
     tags-sorter: alpha
     display-request-duration: true