docs/modules/ROOT/pages/reference/extensions/rest-openapi.adoc

// Do not edit directly!
// This file was generated by camel-quarkus-maven-plugin:update-extension-doc-page
[id="extensions-rest-openapi"]
= REST OpenApi
:page-aliases: extensions/rest-openapi.adoc
:linkattrs:
:cq-artifact-id: camel-quarkus-rest-openapi
:cq-native-supported: true
:cq-status: Stable
:cq-status-deprecation: Stable
:cq-description: To call REST services using OpenAPI specification as contract.
:cq-deprecated: false
:cq-jvm-since: 1.0.0
:cq-native-since: 1.0.0

ifeval::[{doc-show-badges} == true]
[.badges]
[.badge-key]##JVM since##[.badge-supported]##1.0.0## [.badge-key]##Native since##[.badge-supported]##1.0.0##
endif::[]

To call REST services using OpenAPI specification as contract.

[id="extensions-rest-openapi-whats-inside"]
== What's inside

* xref:{cq-camel-components}::rest-openapi-component.adoc[REST OpenApi component], URI syntax: `rest-openapi:specificationUri#operationId`

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

[id="extensions-rest-openapi-maven-coordinates"]
== Maven coordinates

https://{link-quarkus-code-generator}/?extension-search=camel-quarkus-rest-openapi[Create a new project with this extension on {link-quarkus-code-generator}, window="_blank"]

Or add the coordinates to your existing project:

[source,xml]
----
<dependency>
    <groupId>org.apache.camel.quarkus</groupId>
    <artifactId>camel-quarkus-rest-openapi</artifactId>
</dependency>
----
ifeval::[{doc-show-user-guide-link} == true]
Check the xref:user-guide/index.adoc[User guide] for more information about writing Camel Quarkus applications.
endif::[]

[id="extensions-rest-openapi-usage"]
== Usage
[id="extensions-rest-openapi-usage-required-dependencies"]
=== Required Dependencies

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

* camel-quarkus-http
ifeval::[{doc-show-advanced-features} == true]
* camel-quarkus-netty-http
endif::[]

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

[source,xml]
----
<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:

[source]
----
quarkus.native.resources.includes=openapi.json
----

[id="extensions-rest-openapi-usage-contract-first-development"]
=== 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:

[source,xml]
----
<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:

[source,properties]
----
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`

[source,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

[source,properties]
----
quarkus.native.resources.includes=contract.json
----



[id="extensions-rest-openapi-additional-camel-quarkus-configuration"]
== Additional Camel Quarkus configuration

[width="100%",cols="80,5,15",options="header"]
|===
| Configuration property | Type | Default


|icon:lock[title=Fixed at build time] [[quarkus.camel.openapi.codegen.enabled]]`link:#quarkus.camel.openapi.codegen.enabled[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`

|icon:lock[title=Fixed at build time] [[quarkus.camel.openapi.codegen.model-package]]`link:#quarkus.camel.openapi.codegen.model-package[quarkus.camel.openapi.codegen.model-package]`

The package to use for generated model classes.
| `string`
| `org.apache.camel.quarkus`

|icon:lock[title=Fixed at build time] [[quarkus.camel.openapi.codegen.models]]`link:#quarkus.camel.openapi.codegen.models[quarkus.camel.openapi.codegen.models]`

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

|icon:lock[title=Fixed at build time] [[quarkus.camel.openapi.codegen.use-bean-validation]]`link:#quarkus.camel.openapi.codegen.use-bean-validation[quarkus.camel.openapi.codegen.use-bean-validation]`

If `true`, use bean validation annotations in the generated model classes.
| `boolean`
| `false`

|icon:lock[title=Fixed at build time] [[quarkus.camel.openapi.codegen.not-null-jackson]]`link:#quarkus.camel.openapi.codegen.not-null-jackson[quarkus.camel.openapi.codegen.not-null-jackson]`

If `true`, use NON_NULL Jackson annotation in the generated model classes.
| `boolean`
| `false`
|===

[.configuration-legend]
{doc-link-icon-lock}[title=Fixed at build time] Configuration property fixed at build time. All other configuration properties are overridable at runtime.