OpenAPI

Overview

OpenAPI is a specification for machine-readable interface definition for describing, producing, consuming, and visualizing RESTful web services. Nussknacker can read definition of an OpenAPI interface and generate an enricher component for each operation defined in the interface (service) specification.

Nussknacker supports OpenAPI specification versions 2.x and 3.x (note: 2.x is considered deprecated).

note

Integrations are defined in the UI in the Integrations view of the Designer's side menu, available in Nussknacker Cloud and in Enterprise deployments. If you use the OSS edition, check the Open Source version integrations documentation for details on how to configure integrations in configuration files.

Integration parameters

Parameter	Description -
Integration name	Unique name for the integration
Spec URL	URL of the OpenAPI interface definition. It contains definition of the service you want to interact with.
Server URL	The URL of the service. If not specified, the URL of the service is taken from the OpenAPI interface definition.
API Key	API key that will be passed to the service via header, query parameter or cookie, as indicated in the OpenAPI interface definition
Username	Username for Basic authentication, sent with the password on every call.
Password	Password for Basic authentication.

The definition is fetched without credentials. When its server answers 401 asking for Basic or Bearer authentication, it is fetched again with the Username and Password, or with the API Key as a bearer token. The server must name the scheme in the WWW-Authenticate header of its 401: one without it, or one asking only for other schemes, is reported as an error and not retried. The credentials go to the server of the Spec URL, also when it is another than the one of the Server URL, so use a Spec URL you trust with them. OAuth2 client credentials are not used to fetch the definition: with both an API Key and OAuth2 configured, a Bearer challenge gets the API Key.

Additional info

Nussknacker applies following rules when mapping OpenAPI operations to enrichers:

• 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 Type	OpenAPI Format	Type in Nussknacker
boolean		Boolean
string		String
string	date-time	LocalDateTime
integer		Long
integer	int32	Integer
integer	int64	Long
number		BigDecimal
number	double	Double
number	float	Double
array		array
map/object		record

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.