This is an automated email from the ASF dual-hosted git repository.
davsclaus pushed a commit to branch openapi2
in repository https://gitbox.apache.org/repos/asf/camel.git
commit 0a2c51b7cbdd73da6c0ed58fec714367c139bf4c
Author: Claus Ibsen <claus.ib...@gmail.com>
AuthorDate: Wed Mar 27 17:43:19 2024 +0100
CAMEL-20557: Rest DSL to use openapi spec directly
---
.../working-with-camel-core/pages/index.adoc | 1 +
docs/user-manual/modules/ROOT/nav.adoc | 1 +
docs/user-manual/modules/ROOT/pages/dsl.adoc | 1 +
docs/user-manual/modules/ROOT/pages/index.adoc | 1 +
.../modules/ROOT/pages/rest-dsl-openapi.adoc | 128 +++++++++++++++++++++
docs/user-manual/modules/ROOT/pages/rest-dsl.adoc | 4 +
6 files changed, 136 insertions(+)
diff --git a/docs/main/modules/working-with-camel-core/pages/index.adoc
b/docs/main/modules/working-with-camel-core/pages/index.adoc
index 5d7409a0bd0..d1bcda18e29 100644
--- a/docs/main/modules/working-with-camel-core/pages/index.adoc
+++ b/docs/main/modules/working-with-camel-core/pages/index.adoc
@@ -100,6 +100,7 @@ Learn about additional ways to customize your integrations.
Explore alternatives
** xref:manual::property-binding.adoc[Property Binding]
** xref:manual::registry.adoc[Registry]
** xref:manual::rest-dsl.adoc[Rest DSL]
+** xref:manual::rest-dsl-openapi.adoc[Rest DSL contract first with OpenAPI]
** xref:manual::route-configuration.adoc[Route Configuration]
** xref:manual::service-registry.adoc[Service Registry]
** xref:manual::spring.adoc[Spring]
diff --git a/docs/user-manual/modules/ROOT/nav.adoc
b/docs/user-manual/modules/ROOT/nav.adoc
index d83bce43922..b7413027ae3 100644
--- a/docs/user-manual/modules/ROOT/nav.adoc
+++ b/docs/user-manual/modules/ROOT/nav.adoc
@@ -25,6 +25,7 @@
*** xref:notify-builder.adoc[NotifyBuilder]
*** xref:advice-with.adoc[AdviceWith]
** xref:rest-dsl.adoc[Working with REST and Rest DSL]
+*** xref:rest-dsl-openapi.adoc[Rest DSL contract first]
** xref:writing-components.adoc[Writing Components]
** xref:release-guide.adoc[Release guide]
*** xref:release-guide-website.adoc[Adding doc versions to the website]
diff --git a/docs/user-manual/modules/ROOT/pages/dsl.adoc
b/docs/user-manual/modules/ROOT/pages/dsl.adoc
index 609dc0f3cf5..01d7db85190 100644
--- a/docs/user-manual/modules/ROOT/pages/dsl.adoc
+++ b/docs/user-manual/modules/ROOT/pages/dsl.adoc
@@ -10,6 +10,7 @@ languages (DSL) as listed below:
* xref:components::spring-summary.adoc[Spring XML] - A XML based DSL in
classic Spring XML files.
* xref:components:others:yaml-dsl.adoc[Yaml DSL] for creating routes using
YAML format.
* xref:rest-dsl.adoc[Rest DSL] - A DSL to define REST services using REST
verbs.
+** xref:rest-dsl-openapi.adoc[Rest DSL contract first] - Rest DSL using
_contract first_ when OpenAPI specs.
* xref:components:others:groovy-dsl.adoc[Groovy DSL] - A Groovy-based DSL to
create routes leveraging closures and a specific Groovy extension module.
* xref:components:others:kotlin-dsl.adoc[Kotlin DSL] - A Kotlin-based DSL.
* xref:bean-integration.adoc[Annotation DSL] - Use annotations in Java beans.
diff --git a/docs/user-manual/modules/ROOT/pages/index.adoc
b/docs/user-manual/modules/ROOT/pages/index.adoc
index 99c372f0ac0..7bc73e2fb4d 100644
--- a/docs/user-manual/modules/ROOT/pages/index.adoc
+++ b/docs/user-manual/modules/ROOT/pages/index.adoc
@@ -62,6 +62,7 @@ For a deeper and better understanding of Apache Camel, an
xref:faq:what-is-camel
* xref:camel-maven-archetypes.adoc[Camel Maven Archetypes]
* xref:components::jmx-component.adoc[Camel JMX]
* xref:rest-dsl.adoc[Working with REST and Rest DSL]
+** xref:rest-dsl-openapi.adoc[Rest DSL contract first with OpenAPI]
* xref:writing-components.adoc[Writing Custom Camel Components]
=== xref:architecture.adoc[Architecture]
diff --git a/docs/user-manual/modules/ROOT/pages/rest-dsl-openapi.adoc
b/docs/user-manual/modules/ROOT/pages/rest-dsl-openapi.adoc
new file mode 100644
index 00000000000..2e577c202e9
--- /dev/null
+++ b/docs/user-manual/modules/ROOT/pages/rest-dsl-openapi.adoc
@@ -0,0 +1,128 @@
+= REST DSL with contract first OpenAPI
+
+From *Camel 4.6* onwards the xref:rest-dsl.adoc[Rest DSL] has been improved
with a _contract first_
+approach using vanilla OpenAPI specification.
+
+== How it works
+
+The Rest DSL OpenAPI is a facade that builds
xref:components::rest-openapi-component.adoc[Rest OpenAPI] endpoint as
+consumer for Camel routes. The actual HTTP transport is leveraged by using the
xref:components::platform-http-component.adoc[Platform HTTP],
+which makes it plugin to Camel Spring Boot, Camel Quarkus or can run
standalone with Camel Main.
+
+== Contract first
+
+The _contract first_ approach requires you to have an existing OpenAPI v3
specification file.
+This contract is a standard OpenAPI contract, and you can use any existing API
design tool to build such contracts.
+
+TIP: Camel support OpenAPI v3.0 and v3.1.
+
+In Camel, you then use the Rest DSL in _contract first_ mode. For example
having a contracted in a file named `my-contract.json`,
+you can then copy this file to `src/main/resources` so its loaded from
classpath.
+
+In Camel Rest DSL you can then very easily define _contract first_ as shown
below:
+
+
+[tabs]
+====
+Java::
++
+[source,java]
+----
+@Override
+public void configure() throws Exception {
+ rest().openApi("petstore-v3.json");
+}
+----
+XML::
++
+[source,xml]
+----
+<rest>
+ <openApi specification="petstore-v3.json"/>
+</rest>
+----
+YAML::
++
+[source,yaml]
+----
+- rest:
+ openApi:
+ specification: petstore-v3.json
+----
+====
+
+When Camel startup the OpenAPI specification file is loaded and parsed. For
every APIs
+Camel builds HTTP REST endpoint, which are routed 1:1 to Camel routes using
the `direct:operationId` naming convention.
+
+The _pestore_ has 18 APIs here we look at the 5 user APIs:
+
+[source,text]
+----
+ http://0.0.0.0:8080/api/v3/user (POST)
(accept:application/json,application/x-www-form-urlencoded,application/xml
produce:application/json,application/xml)
+ http://0.0.0.0:8080/api/v3/user/createWithList (POST)
(accept:application/json produce:application/json,application/xml)
+ http://0.0.0.0:8080/api/v3/user/login (GET)
(produce:application/json,application/xml)
+ http://0.0.0.0:8080/api/v3/user/logout (GET)
+ http://0.0.0.0:8080/api/v3/user/{username} (DELETE,GET,PUT)
+----
+
+These APIs are outputted using the URI that clients can use to call the
service.
+Each of these APIs has a unique _operation id_ which is what Camel uses for
calling the route. This gives:
+
+[source,text]
+----
+ http://0.0.0.0:8080/api/v3/user direct:createUser
+ http://0.0.0.0:8080/api/v3/user/createWithList
direct:createUsersWithListInput
+ http://0.0.0.0:8080/api/v3/user/login direct:loginUser
+ http://0.0.0.0:8080/api/v3/user/logout direct:logoutUser
+ http://0.0.0.0:8080/api/v3/user/{username} direct:getUserByName
+----
+
+You should then implement a route for each API that starts from those direct
endpoints listed above, such as:
+
+[tabs]
+====
+Java::
++
+[source,java]
+----
+@Override
+public void configure() throws Exception {
+ rest().openApi("petstore-v3.json");
+
+ from("direct:getUserByName")
+ ... // do something here
+}
+----
+XML::
++
+[source,xml]
+----
+<rest>
+ <openApi specification="petstore-v3.json"/>
+</rest>
+<route>
+ <from uri="direct:getUserByName"/>
+ // do something here
+</route>
+----
+YAML::
++
+[source,yaml]
+----
+- rest:
+ openApi:
+ specification: petstore-v3.json
+- route:
+ from:
+ uri: direct:getUserByName
+ steps:
+ - log:
+ message: "do something here"
+----
+====
+
+
+== Client Request Validation
+
+TODO: Does not yet work
+
diff --git a/docs/user-manual/modules/ROOT/pages/rest-dsl.adoc
b/docs/user-manual/modules/ROOT/pages/rest-dsl.adoc
index da30ec0b68a..07d3e87f069 100644
--- a/docs/user-manual/modules/ROOT/pages/rest-dsl.adoc
+++ b/docs/user-manual/modules/ROOT/pages/rest-dsl.adoc
@@ -5,6 +5,10 @@ Apache Camel offers a REST styled DSL.
The intention is to allow end users to define REST services (hosted by Camel)
using a
REST style with verbs such as get, post, delete etc.
+NOTE: From *Camel 4.6* onwards the Rest DSL has been improved with a _contract
first_ approach using vanilla OpenAPI specification
+files. This is documented in the xref:rest-dsl-openapi.adoc[Rest DSL with
OpenAPI contract first] page. This current page documents the
+_code first_ Rest DSL that Camel provides for a long time.
+
== How it works
The Rest DSL is a facade that builds
xref:components::rest-component.adoc[Rest] endpoints as
