Camunda REST

Экспериментальный модуль

Эксперементальный модуль является полностью рабочим и протестированным, но требует дополнительной апробации и аналитики по использованию, по этой причине API может потенциально притерпеть незначительные изменения перед полной готовностью.

Модуль для подключения REST API для Camunda 7 BPMN модуля

Подключение¶

Java Kotlin

Зависимость build.gradle:

implementation "ru.tinkoff.kora.experimental:camunda-rest-undertow"

Модуль:

@KoraApp
public interface Application extends CamundaRestUndertowModule { }

Зависимость build.gradle.kts:

implementation("ru.tinkoff.kora.experimental:camunda-rest-undertow")

Модуль:

@KoraApp
interface Application : CamundaRestUndertowModule

Требует подключения Camunda BPMN модуля.

Конфигурация¶

Пример полной конфигурации, описанной в классе CamundaRestConfig (указаны примеры значений или значения по умолчанию):

Hocon YAML

camunda {
    rest {
        enabled = false //(1)!
        path = "/engine-rest" //(2)!
        port = 8081 //(3)!
        shutdownWait = "30s" //(4)!
        openapi {
            file = [ "openapi.json" ] //(5)!
            enabled = false  //(6)!
            endpoint = "/openapi" //(7)!
            swaggerui {
                enabled = false //(8)!
                endpoint = "/swagger-ui" //(9)!
            }
            rapidoc {
                enabled = false //(10)!
                endpoint = "/rapidoc" //(11)!
            }
        }
        cors {
            enabled = false //(12)!
            allowOrigin = "*" //(13)!
            allowHeaders = [ "*" ] //(14)!
            allowMethods = [ "GET", "POST", "PUT", "DELETE", "PATCH", "OPTIONS", "HEAD" ] //(15)!
            allowCredentials = true //(16)!
            exposeHeaders = [ "*" ] //(17)!
            maxAge = "1h" //(18)!
        }
        telemetry {
            logging {
                enabled = false //(19)!
                stacktrace = true //(20)!
                mask = "***" //(21)!
                maskQueries = [ ] //(22)!
                maskHeaders = [ "authorization", "cookie", "set-cookie" ] //(23)!
                pathTemplate = true //(24)!
            }
            metrics {
                enabled = true //(25)!
                slo = [ 1, 10, 50, 100, 200, 500, 1000, 2000, 5000, 10000, 20000, 30000, 60000, 90000 ] //(26)!
            }
            tracing {
                enabled = true //(27)!
            }
        }
    }
}

Включить/выключить REST API
Путь префикс до REST API
Порт на котором будет запускаться REST API сервер
Максимальное время ожидания штатного завершения
Относительный путь до OpenAPI файлов в resources директории, по умолчанию указан файл openapi.json OpenAPI из зависимости Camunda
Вкл/Выкл контроллера который отдает OpenAPI
Путь по которому будет доступен OpenAPI
1. Если указан один OpenAPI файл, является целиком путем по которому доступен файл
2. Если указаны несколько OpenAPI файлов, является префиксом к пути перед именем файла /openapi/{fileName}, берется указанный путь и к нему добавляется имя файла без диреторий и его расширения, в случае файла someDirectory/my-openapi-1.yaml путь к файлу будет /openapi/my-openapi-1
Вкл/Выкл контроллера который отдает SwaggerUI
Путь по которому будет доступен SwaggerUI
Вкл/Выкл контроллера который отдает Rapidoc
Путь по которому будет доступен Rapidoc
Включает CORS фильтр (по умолчанию false)
Разрешенные источники для CORS (по умолчанию null)
Разрешенные заголовки для CORS запросов (по умолчанию ["*"])
Разрешенные HTTP методы для CORS запросов (по умолчанию ["GET", "POST", "PUT", "DELETE", "PATCH", "OPTIONS", "HEAD"])
Разрешает передачу учетных данных в CORS запросах (по умолчанию true)
Заголовки, которые могут быть доступны клиенту в CORS ответе (по умолчанию ["*"])
Максимальное время кэширования preflight запросов CORS (по умолчанию 1 час)
Включает логгирование модуля (по умолчанию false)
Включает логгирование стэка вызовов в случае исключения
Маска которая используется для скрытия указанных заголовков и параметров запроса/ответа
Список параметров запроса которые следует скрывать
Список заголовков запроса/ответа которые следует скрывать
Использовать ли всегда шаблон пути запроса при логгировании. По умолчанию используется всегда шаблон пути, за исключением уровня логирования TRACE где использует полный путь.
Включает метрики модуля (по умолчанию true)
Настройка SLO для DistributionSummary метрики
Включает трассировку модуля (по умолчанию true)

camunda:
  rest:
    enabled: false #(1)!
    path: "/engine-rest" #(2)!
    port: 8081 #(3)!
    shutdownWait: "30s" #(4)!
    openapi:
      file: [ "openapi.json" ] #(5)!
      enabled: false  #(6)!
      endpoint: "/openapi" #(7)!
      swaggerui:
        enabled: false #(8)!
        endpoint: "/swagger-ui" #(9)!
      rapidoc:
        enabled: false #(10)!
        endpoint: "/rapidoc" #(11)!
      cors:
        enabled: false #(12)!
        allowOrigin: "*" #(13)!
        allowHeaders: [ "*" ] #(14)!
        allowMethods: [ "GET", "POST", "PUT", "DELETE", "PATCH", "OPTIONS", "HEAD" ] #(15)!
        allowCredentials: true #(16)!
        exposeHeaders: [ "*" ] #(17)!
        maxAge: "1h" #(18)!
    telemetry:
      logging:
        enabled: false #(19)!
        stacktrace: true #(20)!
        mask: "***" #(21)!
        maskQueries: [ ] #(22)!
        maskHeaders: [ "authorization", "cookie", "set-cookie" ] #(23)!
        pathTemplate: true #(24)!
      metrics:
        enabled: true #(25)!
        slo: [ 1, 10, 50, 100, 200, 500, 1000, 2000, 5000, 10000, 20000, 30000, 60000, 90000 ] #(26)!
      tracing:
        enabled: true #(27)!

Включить/выключить REST API
Путь префикс до REST API
Порт на котором будет запускаться REST API сервер
Максимальное время ожидания штатного завершения
Относительный путь до OpenAPI файлов в resources директории, по умолчанию указан файл openapi.json OpenAPI из зависимости Camunda
Вкл/Выкл контроллера который отдает OpenAPI
Путь по которому будет доступен OpenAPI
1. Если указан один OpenAPI файл, является целиком путем по которому доступен файл
2. Если указаны несколько OpenAPI файлов, является префиксом к пути перед именем файла /openapi/{fileName}, берется указанный путь и к нему добавляется имя файла без диреторий и его расширения, в случае файла someDirectory/my-openapi-1.yaml путь к файлу будет /openapi/my-openapi-1
Вкл/Выкл контроллера который отдает SwaggerUI
Путь по которому будет доступен SwaggerUI
Вкл/Выкл контроллера который отдает Rapidoc
Путь по которому будет доступен Rapidoc
Включает CORS фильтр (по умолчанию false)
Разрешенные источники для CORS (по умолчанию null)
Разрешенные заголовки для CORS запросов (по умолчанию ["*"])
Разрешенные HTTP методы для CORS запросов (по умолчанию ["GET", "POST", "PUT", "DELETE", "PATCH", "OPTIONS", "HEAD"])
Разрешает передачу учетных данных в CORS запросах (по умолчанию true)
Заголовки, которые могут быть доступны клиенту в CORS ответе (по умолчанию ["*"])
Максимальное время кэширования preflight запросов CORS (по умолчанию 1 час)
Включает логгирование модуля (по умолчанию false)
Включает логгирование стэка вызовов в случае исключения
Маска которая используется для скрытия указанных заголовков и параметров запроса/ответа
Список параметров запроса которые следует скрывать
Список заголовков запроса/ответа которые следует скрывать
Использовать ли всегда шаблон пути запроса при логгировании. По умолчанию используется всегда шаблон пути, за исключением уровня логирования TRACE где использует полный путь.
Включает метрики модуля (по умолчанию true)
Настройка SLO для DistributionSummary метрики
Включает трассировку модуля (по умолчанию true)

Приложения¶

Можно регистрировать произвольные jakarta.ws.rs.core.Application с ресурсами для API (например для других webapp) предоставляя их как компоненты в контейнер зависимостей.