REST OpenApi
Since Camel 3.1
Only producer is supported
The REST OpenApi* configures rest producers from OpenApi (Open API) specification document and delegates to a component implementing the RestProducerFactory interface. Currently known working components are:
Maven users will need to add the following dependency to their
pom.xml
for this component:
<dependency>
<groupId>org.apache.camel</groupId>
<artifactId>camel-rest-openapi</artifactId>
<version>x.x.x</version>
<!-- use the same version as your Camel core version -->
</dependency>
URI format
rest-openapi:[specificationPath#]operationId
Where operationId
is the ID of the operation in the OpenApi
specification, and specificationPath
is the path to the
specification.
If the specificationPath
is not specified it defaults to
openapi.json
. The lookup mechanism uses Camels ResourceHelper
to
load the resource, which means that you can use CLASSPATH resources
(classpath:my-specification.json
), files
(file:/some/path.json
), the web
(http://api.example.com/openapi.json
) or reference a bean
(ref:nameOfBean
) or use a method of a bean
(bean:nameOfBean.methodName
) to get the specification resource,
failing that OpenApi’s own resource loading support.
This component does not act as a HTTP client, it delegates that to
another component mentioned above. The lookup mechanism searches for a
single component that implements the RestProducerFactory interface and
uses that. If the CLASSPATH contains more than one, then the property
componentName
should be set to indicate which component to delegate
to.
Most of the configuration is taken from the OpenApi specification but
the option exists to override those by specifying them on the component
or on the endpoint. Typically you would just need to override the
host
or basePath
if those differ from the specification.
The |
With componentName
you specify what component is used to perform the
requests, this named component needs to be present in the Camel context
and implement the required RestProducerFactory interface — as do the
components listed at the top.
If you do not specify the componentName at either component or endpoint level, CLASSPATH is searched for a suitable delegate. There should be only one component present on the CLASSPATH that implements the RestProducerFactory interface for this to work.
This component’s endpoint URI is lenient which means that in addition
to message headers you can specify REST operation’s parameters as
endpoint parameters, these will be constant for all subsequent
invocations so it makes sense to use this feature only for parameters
that are indeed constant for all invocations — for example API version
in path such as /api/{version}/users/{id}
.
Configuring Options
Camel components are configured on two separate levels:
-
component level
-
endpoint level
Configuring Component Options
The component level is the highest level which holds general and common configurations that are inherited by the endpoints. For example a component may have security settings, credentials for authentication, urls for network connection and so forth.
Some components only have a few options, and others may have many. Because components typically have pre configured defaults that are commonly used, then you may often only need to configure a few options on a component; or none at all.
Configuring components can be done with the Component DSL, in a configuration file (application.properties|yaml), or directly with Java code.
Configuring Endpoint Options
Where you find yourself configuring the most is on endpoints, as endpoints often have many options, which allows you to configure what you need the endpoint to do. The options are also categorized into whether the endpoint is used as consumer (from) or as a producer (to), or used for both.
Configuring endpoints is most often done directly in the endpoint URI as path and query parameters. You can also use the Endpoint DSL as a type safe way of configuring endpoints.
A good practice when configuring options is to use Property Placeholders, which allows to not hardcode urls, port numbers, sensitive information, and other settings. In other words placeholders allows to externalize the configuration from your code, and gives more flexibility and reuse.
The following two sections lists all the options, firstly for the component followed by the endpoint.
Component Options
The REST OpenApi component supports 10 options, which are listed below.
Name | Description | Default | Type |
---|---|---|---|
API basePath, for example /v2. Default is unset, if set overrides the value present in OpenApi specification. |
String |
||
Name of the Camel component that will perform the requests. The component must be present in Camel registry and it must implement RestProducerFactory service provider interface. If not set CLASSPATH is searched for single component that implements RestProducerFactory SPI. Can be overridden in endpoint configuration. |
String |
||
What payload type this component capable of consuming. Could be one type, like application/json or multiple types as application/json, application/xml; q=0.5 according to the RFC7231. This equates to the value of Accept HTTP header. If set overrides any value found in the OpenApi specification. Can be overridden in endpoint configuration. |
String |
||
Scheme hostname and port to direct the HTTP requests to in the form of https://hostname:port. Can be configured at the endpoint, component or in the corresponding REST configuration in the Camel Context. If you give this component a name (e.g. petstore) that REST configuration is consulted first, rest-openapi next, and global configuration last. If set overrides any value found in the OpenApi specification, RestConfiguration. Can be overridden in endpoint configuration. |
String |
||
Whether the producer should be started lazy (on the first message). By starting lazy you can use this to allow CamelContext and routes to startup in situations where a producer may otherwise fail during starting and cause the route to fail being started. By deferring this startup to be lazy then the startup failure can be handled during routing messages via Camel’s routing error handlers. Beware that when the first message is processed then creating and starting the producer may take a little time and prolong the total processing time of the processing. |
false |
boolean |
|
What payload type this component is producing. For example application/json according to the RFC7231. This equates to the value of Content-Type HTTP header. If set overrides any value present in the OpenApi specification. Can be overridden in endpoint configuration. |
String |
||
Path to the OpenApi specification file. The scheme, host base path are taken from this specification, but these can be overridden with properties on the component or endpoint level. If not given the component tries to load openapi.json resource. Note that the host defined on the component and endpoint of this Component should contain the scheme, hostname and optionally the port in the URI syntax (i.e. https://api.example.com:8080). Can be overridden in endpoint configuration. |
openapi.json |
URI |
|
Whether autowiring is enabled. This is used for automatic autowiring options (the option must be marked as autowired) by looking up in the registry to find if there is a single instance of matching type, which then gets configured on the component. This can be used for automatic configuring JDBC data sources, JMS connection factories, AWS Clients, etc. |
true |
boolean |
|
Customize TLS parameters used by the component. If not set defaults to the TLS parameters set in the Camel context. |
SSLContextParameters |
||
Enable usage of global SSL context parameters. |
false |
boolean |
Endpoint Options
The REST OpenApi endpoint is configured using URI syntax:
rest-openapi:specificationUri#operationId
with the following path and query parameters:
Path Parameters (2 parameters)
Name | Description | Default | Type |
---|---|---|---|
Path to the OpenApi specification file. The scheme, host base path are taken from this specification, but these can be overridden with properties on the component or endpoint level. If not given the component tries to load openapi.json resource from the classpath. Note that the host defined on the component and endpoint of this Component should contain the scheme, hostname and optionally the port in the URI syntax (i.e. http://api.example.com:8080). Overrides component configuration. The OpenApi specification can be loaded from different sources by prefixing with file: classpath: http: https:. Support for https is limited to using the JDK installed UrlHandler, and as such it can be cumbersome to setup TLS/SSL certificates for https (such as setting a number of javax.net.ssl JVM system properties). How to do that consult the JDK documentation for UrlHandler. Default value notice: By default loads openapi.json file. |
openapi.json |
URI |
|
Required ID of the operation from the OpenApi specification. |
String |
Query Parameters (6 parameters)
Name | Description | Default | Type |
---|---|---|---|
API basePath, for example /v2. Default is unset, if set overrides the value present in OpenApi specification and in the component configuration. |
String |
||
Name of the Camel component that will perform the requests. The component must be present in Camel registry and it must implement RestProducerFactory service provider interface. If not set CLASSPATH is searched for single component that implements RestProducerFactory SPI. Overrides component configuration. |
String |
||
What payload type this component capable of consuming. Could be one type, like application/json or multiple types as application/json, application/xml; q=0.5 according to the RFC7231. This equates to the value of Accept HTTP header. If set overrides any value found in the OpenApi specification and. in the component configuration. |
String |
||
Scheme hostname and port to direct the HTTP requests to in the form of https://hostname:port. Can be configured at the endpoint, component or in the corresponding REST configuration in the Camel Context. If you give this component a name (e.g. petstore) that REST configuration is consulted first, rest-openapi next, and global configuration last. If set overrides any value found in the OpenApi specification, RestConfiguration. Overrides all other configuration. |
String |
||
Whether the producer should be started lazy (on the first message). By starting lazy you can use this to allow CamelContext and routes to startup in situations where a producer may otherwise fail during starting and cause the route to fail being started. By deferring this startup to be lazy then the startup failure can be handled during routing messages via Camel’s routing error handlers. Beware that when the first message is processed then creating and starting the producer may take a little time and prolong the total processing time of the processing. |
false |
boolean |
|
What payload type this component is producing. For example application/json according to the RFC7231. This equates to the value of Content-Type HTTP header. If set overrides any value present in the OpenApi specification. Overrides all other configuration. |
String |
Example: PetStore
Checkout the example in the camel-example-rest-openapi
project in
the examples
directory.
For example if you wanted to use the
PetStore provided REST API simply
reference the specification URI and desired operation id from the
OpenApi specification or download the specification and store it as
openapi.json
(in the root) of CLASSPATH that way it will be
automaticaly used. Let’s use the Undertow
component to perform all the requests and Camels excelent support for
Spring Boot.
Here are our dependencies defined in Maven POM file:
<dependency>
<groupId>org.apache.camel.springboot</groupId>
<artifactId>camel-undertow-starter</artifactId>
</dependency>
<dependency>
<groupId>org.apache.camel.springboot</groupId>
<artifactId>camel-rest-openapi-starter</artifactId>
</dependency>
Start by defining the Undertow component and the RestOpenApiComponent:
@Bean
public Component petstore(CamelContext camelContext, UndertowComponent undertow) {
RestOpenApiComponent petstore = new RestOpenApiComponent(camelContext);
petstore.setSpecificationUri("https://petstore3.swagger.io/api/v3/openapi.json");
petstore.setDelegate(undertow);
return petstore;
}
Support in Camel for Spring Boot will auto create the
|
Now in our application we can simply use the ProducerTemplate
to
invoke PetStore REST methods:
@Autowired
ProducerTemplate template;
String getPetJsonById(int petId) {
return template.requestBodyAndHeaders("petstore:getPetById", null, "petId", petId);
}
Spring Boot Auto-Configuration
When using rest-openapi with Spring Boot make sure to use the following Maven dependency to have support for auto configuration:
<dependency>
<groupId>org.apache.camel.springboot</groupId>
<artifactId>camel-rest-openapi-starter</artifactId>
<version>x.x.x</version>
<!-- use the same version as your Camel core version -->
</dependency>
The component supports 11 options, which are listed below.
Name | Description | Default | Type |
---|---|---|---|
Whether autowiring is enabled. This is used for automatic autowiring options (the option must be marked as autowired) by looking up in the registry to find if there is a single instance of matching type, which then gets configured on the component. This can be used for automatic configuring JDBC data sources, JMS connection factories, AWS Clients, etc. |
true |
Boolean |
|
API basePath, for example /v2. Default is unset, if set overrides the value present in OpenApi specification. |
String |
||
Name of the Camel component that will perform the requests. The component must be present in Camel registry and it must implement RestProducerFactory service provider interface. If not set CLASSPATH is searched for single component that implements RestProducerFactory SPI. Can be overridden in endpoint configuration. |
String |
||
What payload type this component capable of consuming. Could be one type, like application/json or multiple types as application/json, application/xml; q=0.5 according to the RFC7231. This equates to the value of Accept HTTP header. If set overrides any value found in the OpenApi specification. Can be overridden in endpoint configuration. |
String |
||
Whether to enable auto configuration of the rest-openapi component. This is enabled by default. |
Boolean |
||
Scheme hostname and port to direct the HTTP requests to in the form of https://hostname:port. Can be configured at the endpoint, component or in the corresponding REST configuration in the Camel Context. If you give this component a name (e.g. petstore) that REST configuration is consulted first, rest-openapi next, and global configuration last. If set overrides any value found in the OpenApi specification, RestConfiguration. Can be overridden in endpoint configuration. |
String |
||
Whether the producer should be started lazy (on the first message). By starting lazy you can use this to allow CamelContext and routes to startup in situations where a producer may otherwise fail during starting and cause the route to fail being started. By deferring this startup to be lazy then the startup failure can be handled during routing messages via Camel’s routing error handlers. Beware that when the first message is processed then creating and starting the producer may take a little time and prolong the total processing time of the processing. |
false |
Boolean |
|
What payload type this component is producing. For example application/json according to the RFC7231. This equates to the value of Content-Type HTTP header. If set overrides any value present in the OpenApi specification. Can be overridden in endpoint configuration. |
String |
||
Path to the OpenApi specification file. The scheme, host base path are taken from this specification, but these can be overridden with properties on the component or endpoint level. If not given the component tries to load openapi.json resource. Note that the host defined on the component and endpoint of this Component should contain the scheme, hostname and optionally the port in the URI syntax (i.e. https://api.example.com:8080). Can be overridden in endpoint configuration. |
URI |
||
Customize TLS parameters used by the component. If not set defaults to the TLS parameters set in the Camel context. The option is a org.apache.camel.support.jsse.SSLContextParameters type. |
SSLContextParameters |
||
camel.component.rest-openapi.use-global-ssl-context-parameters |
Enable usage of global SSL context parameters. |
false |
Boolean |