Skip to main content
Version: 1.9

OpenAPI enrichers

Overview

Nussknacker can use services documented with OpenAPI specification. We use Swagger to parse OpenAPI, versions 2.x and 3.x are supported (version 2.x should be considered as deprecated).

Nussknacker applies following rules when mapping OpenAPI services to enrichers:

  • Each operation is mapped to one enricher
  • If operationId is configured it's used as enricher name, otherwise we create it as concatenation of HTTP method, path and parameters (to provide some level of uniqueness)
  • Parameters (path, query of header) are used to define enricher parameters
  • If specification declares body parameter as object, we expand to parameter list
  • We expect operation to define 200/201 response, returned object is the one that is the result of enricher
  • We map 404 HTTP code to null value of enricher
  • We use externalDocs.url to extract documentation link

Table below describes data types that OpenAPI integration handles:

OpenAPI TypeOpenAPI FormatType in Nussknacker
booleanBoolean
stringString
stringdate-timeLocalDateTime
integerLong
numberBigDecimal
numberdoubleDouble
numberfloatDouble
arrayarray
map/objectrecord

OpenAPI integration can handle schema references. However, we don't support recursive schemas at the moment. Recursive schema occurrences will be replaced with Unknown type.

For objects and maps we use properties to define structure. For arrays, we use items to define type of elements.

Configuration

Sample configuration:

components {
service1: {
providerType: openAPI
url = "http://myservice.com/swagger"
rootUrl = "http://myservice.com/endpoint"
security {
apikey {
type = "apiKey"
apiKeyValue = "34534asfdasf"
}
}
namePattern: "customer.*"
allowedMethods: ["GET", "POST"]
}
}
ParameterRequiredDefaultDescription
urltrueURL with OpenAPI resource
rootUrlfalseBase URL of service, can be used to override value from OpenAPI in NAT settings
allowedMethodsfalse["GET"]Usually only GET services should be used as enrichers are meant to be idempotent and not change data
namePatternfalse.*Regexp for filtering operations by operationId (i.e. enricher name)
securityfalseConfiguration for authentication. Currently only apiKey is supported

Operations

You can enable enricher level runtime logging by pl.touk.nussknacker.openapi.enrichers.[enricher name] to DEBUG. In particular, setting pl.touk.nussknacker.openapi.enrichers level to DEBUG will turn on logging on all enrichers.

Enricher level logging can be enabled: