Zimin A.N.
b601c4636f
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.
3.3 KiB
Ordinis НСИ ЦУОД ОДХ — Integrator Guide
Документация для команд, интегрирующих свои сервисы с Ordinis НСИ ЦУОД. Сюда не входят operator runbooks и архитектурные deep-dives — те материалы во внутренней документации проекта.
Anchor v1 — production LIVE на cluster.142 (с 2026-05-07). Альтум consumers подключены, blue/green cutover завершён.
Что внутри
{% list tabs %}
-
Я интегрирую свой сервис
Начни с обзора API и авторизации.
Дальше:
- Read-side endpoints — как читать справочники
- События (Kafka outbox) — топики
ordinis.cuod.events.* - Webhooks — push-уведомления вместо polling
- Кэширование — TTL / push / snapshot стратегии
-
Я строю UI / клиент
- Cross-references — FK между справочниками
- Bitemporal —
validFrom/validTo+ история - Bundle cuod — список 40 справочников ЦУОД
- Best practices — частые ошибки
-
Я обрабатываю ошибки
- Ошибки и rate limits — error codes, retry strategy
- Лучшие практики — robust integration
-
Я хочу пощупать API
Открой Swagger UI — там можно нажать Authorize → войти через Keycloak (PKCE, без secret) → и сразу делать "Try it out" с реальным JWT. Authorization, error codes, schemas — всё через interactive UI.
{% endlist %}
Среды
| Среда | URL | Auth | Назначение |
|---|---|---|---|
| prod | https://ordinis.k8s.264.nstart.cloud/ |
JWT обязателен | Real users |
| staging | https://ordinis.k8s.265.nstart.cloud/ |
optional (legacy mode) | Dev environment |
| local | http://localhost:8080 |
off | docker-compose dev |
Поддержка
- Запросы новых ролей / scope в Keycloak:
zimin.an@nstart.space - Bug reports / feature requests: через issue tracker (запросить URL у Ordinis team)
Версионирование
API стабилизирован под v1 — breaking changes только через major bump (v2). См.
Best practices для рекомендаций по
обработке появления новых полей в v1 (forward compatibility).
Bundle справочников ЦУОД versioned отдельно (cuod-bundle:1.2.1). Изменение
schemas — minor bump, добавление словарей — minor bump, удаление — major bump
(никогда без уведомления consumers через record.closed events).