2 Commits

Author	SHA1	Message	Date
Zimin A.N.	b601c4636f	feat(swagger): OAuth2/Keycloak PKCE flow в Swagger UI + docs links ... OpenApiConfig: - Добавлена OAuth2 security scheme (authorization_code flow с Keycloak realm `nstart`). Auth/token URLs из ordinis.openapi.oauth.issuer-uri configuration property (default: auth.nstart.space/realms/nstart). - BearerAuth scheme сохранён secondary — для pre-issued tokens из CI/scripts. - Servers list переупорядочен — prod первый, staging второй. - Description обновлён с pointer на /docs/ для full integration guide. application.yml: - springdoc.swagger-ui.oauth: client-id (env override), use-pkce-with- authorization-code-grant=true. Public client `ordinis-swagger` настраивается отдельно в Keycloak — see keycloak-setup-swagger-client.md в ordinis-infra repo. - ORDINIS_OPENAPI_OAUTH_ISSUER_URI env var для override realm на разных окружениях. docs/integration/api/read-endpoints.md: - Swagger UI section обновлён: акцент на Authorize button + Keycloak PKCE login (no client_secret needed), tip про bearerAuth fallback. docs/index.md: - Добавлен tab "Я хочу пощупать API" с link на Swagger UI. После deploy: - https://ordinis.k8s.264.nstart.cloud/swagger-ui.html — Swagger UI - https://ordinis.k8s.264.nstart.cloud/v3/api-docs — OpenAPI spec Authorize → выбрать oauth2 → Keycloak login (PKCE) → Try it out с JWT.	2026-05-08 00:08:29 +03:00
Zimin A.N.	d5268b9395	docs: Diplodoc setup + полное руководство интеграции по API ... Новая документация-as-code на платформе Diplodoc (Yandex open-source) с YFM (Yandex Flavored Markdown). Build → static HTML, deployable куда угодно. Что добавлено: - package.json + .yfm + toc.yaml — Diplodoc setup, навигация для sidebar - index.md — главная страница с tabs для разных audiences - README.md — инструкция для contributors Раздел integration/api/ — 11 страниц про интеграцию consumers: - index — обзор + глоссарий - auth — Keycloak service accounts, scope mapping - read-endpoints — GET /dictionaries, list/by-key, spatial filters - events — Kafka outbox топики, partition keys, idempotency, DLQ - webhooks — HMAC, SSRF guard, retry policy, test ping endpoint - bitemporal — validFrom/validTo + history, future-dated entries, bulk close/export - x-references — FK syntax, validation errors, scope hiding, orphan scanner, v2 cascade preview - caching — TTL / push / snapshot strategies, hybrid pattern - errors — full error code reference (validation/auth/conflict/server), retry strategy - best-practices — 33 numbered rules для consumers - bundle-cuod — все 40 справочников с FK графом и сценариями Обновлены: - ops/README.md — link на новую integration/api/, убран inline <br> - ops/slo.md — broken cross-repo links заменены на text references Build: cd docs && pnpm install && pnpm build → ./_dist (20 HTML files, 7.1M) pnpm serve # → http://localhost:8088 CI deploy job для GitLab Pages — в roadmap (см. docs/README.md). Существующий tech/api-integration.md оставлен в toc как legacy (содержимое мигрировано + расширено в integration/api/).	2026-05-07 23:19:02 +03:00