This is an automated email from the ASF dual-hosted git repository.
zhfeng pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/camel-quarkus.git
The following commit(s) were added to refs/heads/main by this push:
new 3ddfa549f3 Add contract first development section in rest-openapi doc
(#6115)
3ddfa549f3 is described below
commit 3ddfa549f3ccc5d56ebaa98aa1137ac45b955aa4
Author: Zheng Feng <[email protected]>
AuthorDate: Wed May 22 15:10:52 2024 +0800
Add contract first development section in rest-openapi doc (#6115)
---
.../pages/reference/extensions/rest-openapi.adoc | 52 +++++++++++++++++++++
.../rest-openapi/runtime/src/main/doc/usage.adoc | 53 +++++++++++++++++++++-
2 files changed, 104 insertions(+), 1 deletion(-)
diff --git a/docs/modules/ROOT/pages/reference/extensions/rest-openapi.adoc
b/docs/modules/ROOT/pages/reference/extensions/rest-openapi.adoc
index c37b859286..cc02809c46 100644
--- a/docs/modules/ROOT/pages/reference/extensions/rest-openapi.adoc
+++ b/docs/modules/ROOT/pages/reference/extensions/rest-openapi.adoc
@@ -76,6 +76,58 @@ When using the `classpath` resource locator with native
code, the path to the Op
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
+----
+
+Please refer to
https://camel.apache.org/manual/rest-dsl-openapi.html#_contract_first[Camel
Rest DSL Contract First] for more details.
+
[id="extensions-rest-openapi-additional-camel-quarkus-configuration"]
== Additional Camel Quarkus configuration
diff --git a/extensions/rest-openapi/runtime/src/main/doc/usage.adoc
b/extensions/rest-openapi/runtime/src/main/doc/usage.adoc
index 30f8f9670b..7925e402c3 100644
--- a/extensions/rest-openapi/runtime/src/main/doc/usage.adoc
+++ b/extensions/rest-openapi/runtime/src/main/doc/usage.adoc
@@ -24,4 +24,55 @@ When using the `classpath` resource locator with native
code, the path to the Op
[source]
----
quarkus.native.resources.includes=openapi.json
-----
\ No newline at end of file
+----
+
+=== 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
+----
+
+Please refer to
https://camel.apache.org/manual/rest-dsl-openapi.html#_contract_first[Camel
Rest DSL Contract First] for more details.
\ No newline at end of file
