[camel] branch camel-3.x updated: CAMEL-19083: Tidy yaml-dsl docs and link to the schema

[ja...@apache.org]

This is an automated email from the ASF dual-hosted git repository.

jamesnetherton pushed a commit to branch camel-3.x
in repository https://gitbox.apache.org/repos/asf/camel.git


The following commit(s) were added to refs/heads/camel-3.x by this push:
     new 17c76a501ac CAMEL-19083: Tidy yaml-dsl docs and link to the schema
17c76a501ac is described below

commit 17c76a501ac3ac3dac86cdd7fefa4f3ef2e1e0f7
Author: James Netherton <ja...@gmail.com>
AuthorDate: Tue Feb 21 07:25:22 2023 +0000

    CAMEL-19083: Tidy yaml-dsl docs and link to the schema
---
 .../camel-yaml-dsl/src/main/docs/yaml-dsl.adoc     | 151 ++++++++++++---------
 1 file changed, 88 insertions(+), 63 deletions(-)

diff --git a/dsl/camel-yaml-dsl/camel-yaml-dsl/src/main/docs/yaml-dsl.adoc b/dsl/camel-yaml-dsl/camel-yaml-dsl/src/main/docs/yaml-dsl.adoc
index 17ff5d3c9f2..bef9687cd66 100644
--- a/dsl/camel-yaml-dsl/camel-yaml-dsl/src/main/docs/yaml-dsl.adoc
+++ b/dsl/camel-yaml-dsl/camel-yaml-dsl/src/main/docs/yaml-dsl.adoc
@@ -10,6 +10,8 @@
 
 *Since Camel {since}*
 
+The YAML DSL provides the capability to define your Camel routes, route templates & REST DSL configuration in YAML.
+
 == Defining a route
 
 A route is collection of elements defined as follows:
@@ -37,11 +39,11 @@ A route is collection of elements defined as follows:
 Each step is represented by a YAML map that has a single entry where the field name is the EIP name
 ====
 
-As general rule each step provide all the parameters the related definition declares but there are some minor differences/enhancements:
+As a general rule, each step provides all the parameters the related definition declares, but there are some minor differences/enhancements:
 
 - *Output Aware Steps*
 +
-Some steps such as `filter` and `split` have their own pipeline when an exchange matches the filter expression or for the items generated by the split expression, such pipeline can be defined by the `steps` field:
+Some steps such as `filter` and `split` have their own pipeline. When an exchange matches the filter expression or for the items generated by the split expression, such a pipeline can be defined by the `steps` field:
 +
 [source,yaml]
 ----
@@ -56,7 +58,7 @@ filter:
 
 - *Expression Aware Steps*
 +
-Some EIP such as `filter` and `split` supports the definition of an expression through the `expression` field:
+Some EIPs such as `filter` and `split` support the definition of an expression through the `expression` field:
 +
 [source,yaml]
 .Explicit Expression field
@@ -75,7 +77,7 @@ filter:
   simple: "${in.header.continue} == true"
 ----
 +
-In general expression can be defined inline like in the examples above but in case you need provide more information, you can 'unroll' the expression definition and configure any single parameter the expression defines.
+In general, `expression` can be defined inline like in the examples above. But in case you need to provide more information, you can 'unroll' the expression definition and configure any single parameter the expression defines.
 +
 [source,yaml]
 .Full Expression definition
@@ -104,7 +106,7 @@ In case you want to use the data-format's default settings, you need to place an
 
 == Defining endpoints
 
-To define an endpoint with the YAML dsl you have three options:
+To define an endpoint with the YAML dsl you have two options:
 
 . Using a classic Camel URI:
 +
@@ -133,7 +135,7 @@ To define an endpoint with the YAML dsl you have three options:
 
 == Defining beans
 
-In addition to the general support for creating beans provided by xref:others:main.adoc#_specifying_custom_beans[Camel Main], the YAML DSL provide a convenient syntax to define and configure them:
+In addition to the general support for creating beans provided by xref:others:main.adoc#_specifying_custom_beans[Camel Main], the YAML DSL provides a convenient syntax to define and configure them:
 
 [source,yaml]
 ----
@@ -148,7 +150,7 @@ In addition to the general support for creating beans provided by xref:others:ma
 <2> the full qualified class name of the bean
 <3> the properties of the bean to be set
 
-The properties of the bean can be defined using either a map or properties style as shown in the example below:
+The properties of the bean can be defined using either a map or properties style, as shown in the example below:
 
 [source,yaml]
 ----
@@ -174,7 +176,7 @@ The properties of the bean can be defined using either a map or properties style
 
 [NOTE]
 ====
-The `beans` elements can only be used as root element
+The `beans` elements can only be used as the root element
 ====
 
 == Configuring options on languages
@@ -182,13 +184,13 @@ The `beans` elements can only be used as root element
 Some xref:components:languages:index.adoc[Languages] have additional configurations
 you may need to use.
 
-For example the xref:components:languages:jsonpath-language.adoc[JSONPath]
+For example, the xref:components:languages:jsonpath-language.adoc[JSONPath]
 can be configured to ignore JSon parsing errors. This is intended when you use a
 xref:components:eips:choice-eip.adoc[Content Based Router] and want to route the message
-to different endpoints, but the JSon payload of the message can be in different forms;
-meaning that the JSonPath expressions in some cases would fail with an exceptions,
-and other times not. In this situation you need to set `suppress-exception` to true,
-as shown belo:
+to different endpoints. But the JSon payload of the message can be in different forms;
+meaning that the JSonPath expressions in some cases would fail with an exception,
+and other times not. In this situation, you need to set `suppress-exception` to true,
+as shown below:
 
 [source,yaml]
 ----
@@ -235,53 +237,76 @@ which demonstrate creating Camel Routes with YAML.
 Another way to find examples of YAML DSL is to look in https://github.com/apache/camel-kamelets[Camel Kamelets]
 where each Kamelet is defined using YAML.
 
-== Camel K support
-
-The `camel-yaml-dsl` is supported by Camel K.
-
-=== Loading Camel K integrations
-
-A Camel K integration (in CRD format (Custom Resource Definition in Kubernetes))
-can be loaded by `camel-yaml-dsl` and run as routes:
-
-[source,yaml]
-----
-apiVersion: camel.apache.org/v1
-kind: Integration
-metadata:
-  name: hello.yaml
-spec:
-  flows:
-    - from:
-        uri: "timer:tick?period=5000"
-      steps:
-        - to: "log:tick"
-----
-
-=== Loading Camel K bindings
-
-A Camel K binding (in CRD format; Custom Resource Definition in Kubernetes)
-can be loaded by `camel-yaml-dsl` and run as routes:
-
-[source,yaml]
-----
-apiVersion: camel.apache.org/v1alpha1
-kind: KameletBinding
-metadata:
-  name: joke
-spec:
-  source:
-    ref:
-      kind: Kamelet
-      apiVersion: camel.apache.org/v1
-      name: chuck-norris-source
-    properties:
-      period: 2000
-  sink:
-    ref:
-      kind: Kamelet
-      apiVersion: camel.apache.org/v1
-      name: log-sink
-    properties:
-      show-headers: false
-----
+== Supported EIPs
+
+The following set of high level EIPs are supported in the yaml DSL language. For full details on their expected configuration, please refer to the https://github.com/apache/camel/blob/main/dsl/camel-yaml-dsl/camel-yaml-dsl/src/generated/resources/schema/camel-yaml-dsl.json[Camel YAML DSL specification].
+
+- Aggregate
+- Bean
+- Do Catch
+- Do Try
+- Do Finally
+- Choice
+- Circuit Breaker
+- Claim Check
+- Convert Body To
+- Delay
+- Dynamic Router
+- Enrich
+- Error Handler
+- Filter
+- From
+- Idempotent Consumer
+- Intercept
+- Intercept From
+- Intercept Send To Endpoint
+- Load Balance
+- Log
+- Loop
+- Marshal
+- Multicast
+- On Completion
+- On Exception
+- On Fallback
+- Otherwise
+- Pausable
+- Pipeline
+- Policy
+- Poll Enrich
+- Process
+- Recipient List
+- Remove Header
+- Remove Headers
+- Remove Property
+- Remove Properties
+- Resequence
+- Resumable
+- REST DSL
+- Rollback
+- Routing Slip
+- Saga
+- Sample
+- Script
+- Service Call
+- Set Body
+- Set Exchange Pattern
+- Set Header
+- Set Property
+- Sort
+- Split
+- Step
+- Stop
+- Threads
+- Throttle
+- Throw Exception
+- To
+- To Dynamic
+- Transacted
+- Transform
+- Unmarshal
+- Validate
+- When
+- When Skip Send To Endpoint
+- Wire Tap
+
+NOTE: The Try / Catch / Finally EIP currently only supports specifying one `do-catch` clause.