// 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

Model class generation has been integrated into 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` or `.yaml` suffix then ensure the `generate-code` goal is configured on the `quarkus-maven-plugin`:

[source,xml]
----
<plugin>
    <groupId>io.quarkus</groupId>
    <artifactId>quarkus-maven-plugin</artifactId>
    <executions>
        <execution>
            <goals>
                <goal>generate-code</goal>
            </goals>
        </execution>
    </executions>
</plugin>
----

You can customize the package name of the generated classes by adding configuration property `quarkus.camel.openapi.codegen.model-package` to `application.properties` file.

[source,properties]
----
quarkus.camel.openapi.codegen.model-package=org.acme
----

In addition, you should also add this package to configuration property `camel.rest.bindingPackageScan`.

The contract files in `src/main/openapi` need to be added in the classpath, since they could be used in the Camel Rest DSL. For example, to do this with Maven:

[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 added to the native image via the `quarkus.native.resources.include` configuration property.

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

[IMPORTANT]
====
It's recommended to configure a base path under which your REST service endpoints will be accessible.

Using the default path `/` can result in other HTTP endpoints already hosted under that path being inaccessible.

To set a base path, do any one of the following.

* Add https://swagger.io/docs/specification/v3_0/api-host-and-base-path/[servers configuration] into your OpenAPI spec file.
* Add configuration to `application.properties` like `camel.component.rest-openapi.basePath=/api/v1`.
* Set a context path on the REST DSL configuration like `restConfiguration().contextPath("/api/v1")`.
====


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

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


a|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 and .yaml files discovered from the `openapi`
directory. When
`false`, code generation for .json and .yaml files is disabled.
| `boolean`
| `true`

a|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`

a|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. The default is empty list for all models.
| `string`
| 

a|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`

a|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`

a|icon:lock[title=Fixed at build time] [[quarkus-camel-openapi-codegen-ignore-unknown-properties]]`link:#quarkus-camel-openapi-codegen-ignore-unknown-properties[quarkus.camel.openapi.codegen.ignore-unknown-properties]`

If `true`, use JsonIgnoreProperties(ignoreUnknown = true) annotation in the generated model classes.
| `boolean`
| `false`

a|icon:lock[title=Fixed at build time] [[quarkus-camel-openapi-codegen-additional-properties-additional-properties]]`link:#quarkus-camel-openapi-codegen-additional-properties-additional-properties[quarkus.camel.openapi.codegen.additional-properties."additional-properties"]`

Additional properties to be used in the mustache templates.
| `Map<String,String>`
| 

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

A comma separated list of OpenAPI spec locations.
| `string`
| 
|===

[.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.

