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 and .yaml files discovered from the `openapi` directory. When `false`, code generation for .json and .yaml 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. The default is empty list for all models.	`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.locations` A comma separated list of OpenAPI spec locations.	`string`

quarkus.camel.openapi.codegen.enabled

If true, Camel Quarkus OpenAPI code generation is run for .json and .yaml files discovered from the openapi directory. When false, code generation for .json and .yaml 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. The default is empty list for all models.

string

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

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

boolean