This is an automated email from the ASF dual-hosted git repository.
jamesnetherton 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 8e95c7e8a3 Add component and endpoint documentation for Qute extension
8e95c7e8a3 is described below
commit 8e95c7e8a3b0b83ddab24bcc0c29473f996109c0
Author: James Netherton <jamesnether...@gmail.com>
AuthorDate: Fri Feb 16 11:54:35 2024 +0000
Add component and endpoint documentation for Qute extension
Fixes #3549
---
.../ROOT/examples/json/camel-quarkus-qute.json | 1 +
.../ROOT/pages/reference/extensions/qute.adoc | 5 +-
.../ROOT/partials/component-configure-options.adoc | 35 +++++
.../ROOT/partials/component-endpoint-headers.adoc | 23 ++++
.../ROOT/partials/component-endpoint-options.adoc | 152 +++++++++++++++++++++
extensions/qute/runtime/src/main/doc/usage.adoc | 5 +-
6 files changed, 219 insertions(+), 2 deletions(-)
diff --git a/docs/modules/ROOT/examples/json/camel-quarkus-qute.json
b/docs/modules/ROOT/examples/json/camel-quarkus-qute.json
new file mode 120000
index 0000000000..26e978f13a
--- /dev/null
+++ b/docs/modules/ROOT/examples/json/camel-quarkus-qute.json
@@ -0,0 +1 @@
+../../../../../extensions/qute/component/src/generated/resources/org/apache/camel/component/qute/qute.json
\ No newline at end of file
diff --git a/docs/modules/ROOT/pages/reference/extensions/qute.adoc
b/docs/modules/ROOT/pages/reference/extensions/qute.adoc
index 524e05ef37..7be8da74f8 100644
--- a/docs/modules/ROOT/pages/reference/extensions/qute.adoc
+++ b/docs/modules/ROOT/pages/reference/extensions/qute.adoc
@@ -40,7 +40,10 @@ endif::[]
[id="extensions-qute-usage"]
== Usage
-Please refer to the https://quarkus.io/guides/qute[Quarkus Qute].
+include::partial$component-configure-options.adoc[]
+include::partial$component-endpoint-options.adoc[]
+
+For more information about Qute, please refer to the
https://quarkus.io/guides/qute[Quarkus Qute] documentation.
[id="extensions-qute-camel-quarkus-limitations"]
diff --git a/docs/modules/ROOT/partials/component-configure-options.adoc
b/docs/modules/ROOT/partials/component-configure-options.adoc
new file mode 100644
index 0000000000..a58fbb4864
--- /dev/null
+++ b/docs/modules/ROOT/partials/component-configure-options.adoc
@@ -0,0 +1,35 @@
+// component-configure options: START
+== Configuring Options
+
+Camel components are configured on two separate levels:
+
+- component level
+- endpoint level
+
+=== Configuring Component Options
+
+The component level is the highest level which holds general and common
configurations that are inherited by the endpoints.
+For example a component may have security settings, credentials for
authentication, urls for network connection and so forth.
+
+Some components only have a few options, and others may have many. Because
components typically have pre configured defaults
+that are commonly used, then you may often only need to configure a few
options on a component; or none at all.
+
+Configuring components can be done with the
xref:manual::component-dsl.adoc[Component DSL],
+in a configuration file (application.properties|yaml), or directly with Java
code.
+
+=== Configuring Endpoint Options
+
+Where you find yourself configuring the most is on endpoints, as endpoints
often have many options, which allows you to
+configure what you need the endpoint to do. The options are also categorized
into whether the endpoint is used as consumer (from)
+or as a producer (to), or used for both.
+
+Configuring endpoints is most often done directly in the endpoint URI as path
and query parameters. You can also use
+the xref:manual::Endpoint-dsl.adoc[Endpoint DSL] and
xref:manual::dataformat-dsl.adoc[DataFormat DSL]
+as a _type safe_ way of configuring endpoints and data formats in Java.
+
+A good practice when configuring options is to use
xref:manual::using-propertyplaceholder.adoc[Property Placeholders],
+which allows to not hardcode urls, port numbers, sensitive information, and
other settings.
+In other words placeholders allows to externalize the configuration from your
code, and gives more flexibility and reuse.
+
+The following two sections lists all the options, firstly for the component
followed by the endpoint.
+// component-configure options: END
diff --git a/docs/modules/ROOT/partials/component-endpoint-headers.adoc
b/docs/modules/ROOT/partials/component-endpoint-headers.adoc
new file mode 100644
index 0000000000..eeda9e706a
--- /dev/null
+++ b/docs/modules/ROOT/partials/component-endpoint-headers.adoc
@@ -0,0 +1,23 @@
+//component headers: START
+
+:tablespec: width="100%",cols="2,5a,^1,2",options="header"
+:cellformats: 'util.boldLink(path[2], "endpoint_header", value.group) +
"\n\nConstant: " + camel.constantLink("{artifactid}",value.constantName) \
+|util.description(value) \
+|util.valueAsString(value.defaultValue) \
+|util.javaSimpleName(value.javaType)'
+include::jsonpathcount$example$json/{cq-artifact-id}.json[queries='headercount=nodes$.headers.*']
+
+ifeval::[{headercount} != 0]
+== Message Headers
+
+The {doctitle} component supports {headercount} message header(s), which
is/are listed below:
+
+[{tablespec}]
+|===
+| Name | Description | Default | Type
+|===
+
+jsonpathTable::example$json/{cq-artifact-id}.json['nodes$.headers.*',{cellformats},'util=camel-website-util,camel=xref:js/camel.js']
+
+endif::[]
+// component headers: END
diff --git a/docs/modules/ROOT/partials/component-endpoint-options.adoc
b/docs/modules/ROOT/partials/component-endpoint-options.adoc
new file mode 100644
index 0000000000..42799b7629
--- /dev/null
+++ b/docs/modules/ROOT/partials/component-endpoint-options.adoc
@@ -0,0 +1,152 @@
+//component options: START
+
+:tablespec: width="100%",cols="2,5a,^1,2",options="header"
+:component-option-name: util.boldLink(path[2], "component_option", value.group)
+:endpoint-path-option-name: util.boldLink(path[2], "endpoint_path_option",
value.group)
+:endpoint-query-option-name: util.boldLink(path[2], "endpoint_query_option",
value.group)
+:last-cell-formats: |util.description(value) \
+|util.valueAsString(value.defaultValue) \
+|util.javaSimpleName(value.javaType)
+include::jsonpath$example$json/{cq-artifact-id}.json[query='$.component',formats='name,scheme,pascalcasescheme=util.pascalCase(scheme),syntax,apiSyntax',
requires={requires}]
+include::jsonpathcount$example$json/{cq-artifact-id}.json[queries='propertycount=nodes$.componentProperties.*,pathparametercount=nodes$.properties[?(@.kind=="path")],queryparametercount=nodes$.properties[?(@.kind=="parameter")],apicount=nodes$.apis.*']
+
+== Component Options
+
+The {doctitle} component supports {propertycount} options, which are listed
below.
+
+[{tablespec}]
+|===
+| Name | Description | Default | Type
+|===
+
+jsonpathTable::example$json/{cq-artifact-id}.json['nodes$.componentProperties.*','{component-option-name}{last-cell-formats}',{requires}]
+
+
+// endpoint options: START
+== Endpoint Options
+
+The {doctitle} endpoint is configured using URI syntax:
+
+[subs='+attributes']
+----
+{syntax}
+----
+
+with the following path and query parameters:
+
+=== Path Parameters ({pathparametercount} parameters)
+
+ifeval::[{pathparametercount} == 0]
+The {doctitle} endpoint has no path parameters.
+endif::[]
+
+ifeval::[{pathparametercount} != 0]
+[{tablespec}]
+|===
+| Name | Description | Default | Type
+|===
+
+jsonpathTable::example$json/{cq-artifact-id}.json['nodes$.properties[?(@.kind=="path")]','{endpoint-path-option-name}{last-cell-formats}',{requires}]
+
+endif::[]
+
+[#_query_parameters]
+=== Query Parameters ({queryparametercount} parameters)
+
+ifeval::[{queryparametercount} == 0]
+The {doctitle} endpoint has no query parameters.
+endif::[]
+
+ifeval::[{queryparametercount} != 0]
+[{tablespec}]
+|===
+| Name | Description | Default | Type
+|===
+
+jsonpathTable::example$json/{cq-artifact-id}.json['nodes$.properties[?(@.kind=="parameter")]','{endpoint-query-option-name}{last-cell-formats}',{requires}]
+endif::[]
+
+ifeval::[{apicount} != 0]
+
+== API Parameters ({apicount} APIs)
+
+The {doctitle} endpoint is an API based component and has additional
parameters based on which API name and API method is used.
+The API name and API method is located in the endpoint URI as the
`{apiSyntax}` path parameters:
+
+[subs='+attributes']
+----
+{syntax}
+----
+
+There are {apicount} API names as listed in the table below:
+
+[width="100%",cols="2,2,6a",options="header"]
+|===
+| API Name | Type | Description
+|===
+
+jsonpathTable::example$json/{cq-artifact-id}.json['nodes$.apis.*','`<<#_api_${path[2]},*${path[2]}*>>`|
value.consumerOnly ? "Consumer" : value.producerOnly ? "Producer" : "Both" |
value.description']
+
+Each API is documented in the following sections to come.
+
+[jsonpathBlock, example$json/{cq-artifact-id}.json,
'nodes$.apis.*','apiname=path[2], producer-consumer =
util.producerConsumerLong(value.consumerOnly\, value.producerOnly),
methodcount=Object.keys(value.methods).length, aliases=value.aliases',
{requires}]
+----
+
+[#_api_{apiname}]
+=== API: {apiName}
+
+*{producer-consumer}*
+
+%ifeval::[{methodcount} == 0]
+The {apiName} has no API methods.
+%endif::[]
+
+%ifeval::[{methodcount} != 0]
+
+The {apiname} API is defined in the syntax as follows:
+
+[source,subs=+attributes]
+------
+{scheme}:{apiname}/methodName?[parameters]
+------
+
+The {methodcount} method(s) is listed in the table below, followed by detailed
syntax for each method.
+(API methods can have a shorthand alias name which can be used in the syntax
instead of the name)
+
+[width="100%",cols="2,2,6a",options="header"]
+|===
+| Method | Alias | Description
+|===
+
+jsonpathTable::example$json/{cq-artifact-id}.json['nodes$.apis["{apiname}"].methods.*','`<<#_api_{apiname}_method_${path[4]},*${path[4]}*>>`|util.alias(path[4],
"{aliases}")|value.description', {requires}]
+
+[jsonpathBlock, example$json/{cq-artifact-id}.json,
'nodes$.apis["{apiname}"].methods.*','methodname=path[4]', {requires}]
+------
+[#_api_{apiname}_method_{methodname}]
+==== Method {methodname}
+
+Signatures:
+
+jsonpathList::example$json/{cq-artifact-id}.json['nodes$.apis["{apiname}"].methods["{methodname}"].signatures.*','util.formatSignature(value)',
{requires}]
+
+The {name}/{methodname} API method has the parameters listed in the table
below:
+
+[width="100%",cols="2,4a,2",options="header"]
+|===
+| Parameter | Description | Type
+|===
+
+jsonpathTable::example$json/{cq-artifact-id}.json['nodes$.apiProperties["{apiname}"].methods["{methodname}"].properties.*','`*${path[6]}*`|`${util.strong(value,
"Required")} ${value.description}`|util.javaSimpleName(value.javaType)',
{requires}]
+
+------
+
+In addition to the parameters above, the {name} API can also use any of the
<<#_query_parameters>>.
+
+Any of the parameters can be provided in either the endpoint URI, or
dynamically in a message header.
+The message header name must be of the format
`Camel{pascalcasescheme}.parameter`.
+The `inBody` parameter overrides message header, i.e. the endpoint parameter
`inBody=myParameterNameHere`
+would override a `Camel{pascalcasescheme}.myParameterNameHere` header.
+
+%endif::[]
+----
+endif::[]
diff --git a/extensions/qute/runtime/src/main/doc/usage.adoc
b/extensions/qute/runtime/src/main/doc/usage.adoc
index 164c993baf..a67aa367e1 100644
--- a/extensions/qute/runtime/src/main/doc/usage.adoc
+++ b/extensions/qute/runtime/src/main/doc/usage.adoc
@@ -1 +1,4 @@
-Please refer to the https://quarkus.io/guides/qute[Quarkus Qute].
\ No newline at end of file
+include::partial$component-configure-options.adoc[]
+include::partial$component-endpoint-options.adoc[]
+
+For more information about Qute, please refer to the
https://quarkus.io/guides/qute[Quarkus Qute] documentation.
