From e2080d899153f78eb35cf7fab7ea59d52fdc151d Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=D0=90=D0=BB=D0=B5=D0=BA=D1=81=D0=B0=D0=BD=D0=B4=D1=80=20?= =?UTF-8?q?=D0=97=D0=B8=D0=BC=D0=B8=D0=BD?= Date: Tue, 12 May 2026 17:43:12 +0000 Subject: [PATCH] =?UTF-8?q?fix(docs,security):=20Swagger=20UI=20=E2=80=94?= =?UTF-8?q?=20staging=20=D0=B4=D0=BB=D1=8F=20exploration,=20prod=20env-fla?= =?UTF-8?q?gged?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- docs/index.md | 6 +++++- docs/integration/api/read-endpoints.md | 17 +++++++++++++---- ordinis-app/src/main/resources/application.yml | 8 ++++++++ 3 files changed, 26 insertions(+), 5 deletions(-) diff --git a/docs/index.md b/docs/index.md index 670ecc1..226ad4f 100644 --- a/docs/index.md +++ b/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 %} ## Что нового в продукте diff --git a/docs/integration/api/read-endpoints.md b/docs/integration/api/read-endpoints.md index 7e743dc..e7cc1ff 100644 --- a/docs/integration/api/read-endpoints.md +++ b/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 %} diff --git a/ordinis-app/src/main/resources/application.yml b/ordinis-app/src/main/resources/application.yml index 7b8e426..9913b0f 100644 --- a/ordinis-app/src/main/resources/application.yml +++ b/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