REST OpenApi

JVM since1.0.0 Native since1.0.0

To call REST services using OpenAPI specification as contract.

What’s inside

REST OpenApi component, URI syntax: rest-openapi:specificationUri#operationId

Please refer to the above link for usage and configuration details.

Maven coordinates

Create a new project with this extension on code.quarkus.io

Or add the coordinates to your existing project:

<dependency>
    <groupId>org.apache.camel.quarkus</groupId>
    <artifactId>camel-quarkus-rest-openapi</artifactId>
</dependency>

Check the User guide for more information about writing Camel Quarkus applications.

Usage

Required Dependencies

A RestProducerFactory implementation must be available when using the rest-openapi extension. The currently known extensions are:

camel-quarkus-http
camel-quarkus-netty-http

Maven users will need to add one of these dependencies to their pom.xml, for example:

<dependency>
    <groupId>org.apache.camel.quarkus</groupId>
    <artifactId>camel-quarkus-http</artifactId>
</dependency>

Depending on which mechanism is used to load the OpenApi specification, additional dependencies may be required. When using the file resource locator, the org.apache.camel.quarkus:camel-quarkus-file extension must be added as a project dependency. When using ref or bean to load the specification, not only must the org.apache.camel.quarkus:camel-quarkus-bean dependency be added, but the bean itself must be annotated with @RegisterForReflection.

When using the classpath resource locator with native code, the path to the OpenAPI specification must be specified in the quarkus.native.resources.includes property of the application.properties file. For example:

quarkus.native.resources.includes=openapi.json

Contract First Development

The model classes generation has been integrated with the quarkus-maven-plugin. So there’s no need to use the swagger-codegen-maven-plugin, instead put your contract files in src/main/openapi with a .json suffix. And add the generate-code goal to the quarkus-maven-plugin like:

<plugin>
    <groupId>io.quarkus</groupId>
    <artifactId>quarkus-maven-plugin</artifactId>
    <executions>
        <execution>
            <goals>
                <goal>generate-code</goal>
            </goals>
        </execution>
    </executions>
</plugin>

It requires a specific package name for the model classes by using the quarkus.camel.openapi.codegen.model-package property of the application.properties file. For example:

quarkus.camel.openapi.codegen.model-package=org.acme

This package name should be added in camel.rest.bindingPackageScan as well.

The contract files in src/main/openapi needs to be added in the classpath since they could be used in Camel Rest DSL. So you can add src/main/openapi in pom.xml

<build>
    <resources>
        <resource>
            <directory>src/main/openapi</directory>
        </resource>
        <resource>
            <directory>src/main/resources</directory>
        </resource>
    </resources>
</build>

When running in the native mode, the contract files must be specified the quarkus.native.resources.include like

quarkus.native.resources.includes=contract.json

Additional Camel Quarkus configuration

Configuration property Type Default

Configuration property	Type	Default
`quarkus.camel.openapi.codegen.enabled` If `true`, Camel Quarkus OpenAPI code generation is run for .json files discovered from the `openapi` directory. When `false`, code generation for .json files is disabled.	`boolean`	`true`
`quarkus.camel.openapi.codegen.model-package` The package to use for generated model classes.	`string`	`org.apache.camel.quarkus`
`quarkus.camel.openapi.codegen.models` A comma separated list of models to generate. All models is the default.	`string`
`quarkus.camel.openapi.codegen.use-bean-validation` If `true`, use bean validation annotations in the generated model classes.	`boolean`	`false`
`quarkus.camel.openapi.codegen.not-null-jackson` If `true`, use NON_NULL Jackson annotation in the generated model classes.	`boolean`	`false`
`quarkus.camel.openapi.codegen.ignore-unknown-properties` If `true`, use JsonIgnoreProperties(ignoreUnknown = true) annotation in the generated model classes.	`boolean`	`false`
`quarkus.camel.openapi.codegen.additional-properties."additional-properties"` Additional properties to be used in the mustache templates.	`Map<String,String>`

quarkus.camel.openapi.codegen.enabled

If true, Camel Quarkus OpenAPI code generation is run for .json files discovered from the openapi directory. When false, code generation for .json files is disabled.

boolean

true

quarkus.camel.openapi.codegen.model-package

The package to use for generated model classes.

string

org.apache.camel.quarkus

quarkus.camel.openapi.codegen.models

A comma separated list of models to generate. All models is the default.

string

quarkus.camel.openapi.codegen.use-bean-validation

If true, use bean validation annotations in the generated model classes.

boolean