You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@camel.apache.org by da...@apache.org on 2020/09/02 18:08:54 UTC
[camel] 01/02: CAMEL-15478: Generate documentation for API
components with their API query parameters in tables per API.
This is an automated email from the ASF dual-hosted git repository.
davsclaus pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/camel.git
commit 8c294490363057a58f31007628cfed220f1d5d91
Author: Claus Ibsen <cl...@gmail.com>
AuthorDate: Wed Sep 2 19:56:36 2020 +0200
CAMEL-15478: Generate documentation for API components with their API query parameters in tables per API.
---
.../camel/component/braintree/braintree.json | 3 ++
.../src/main/docs/braintree-component.adoc | 44 +++++++++++++++++++++-
.../org/apache/camel/tooling/model/JsonMapper.java | 19 ++++++----
.../packaging/EndpointSchemaGeneratorMojo.java | 12 +++++-
.../src/main/resources/endpoint-options.mvel | 4 ++
5 files changed, 72 insertions(+), 10 deletions(-)
diff --git a/components/camel-braintree/src/generated/resources/org/apache/camel/component/braintree/braintree.json b/components/camel-braintree/src/generated/resources/org/apache/camel/component/braintree/braintree.json
index 17f816f..d11a361 100644
--- a/components/camel-braintree/src/generated/resources/org/apache/camel/component/braintree/braintree.json
+++ b/components/camel-braintree/src/generated/resources/org/apache/camel/component/braintree/braintree.json
@@ -67,15 +67,18 @@
"publicKey": { "kind": "parameter", "displayName": "Public Key", "group": "security", "label": "security", "required": false, "type": "string", "javaType": "java.lang.String", "deprecated": false, "secret": true, "configurationClass": "org.apache.camel.component.braintree.BraintreeConfiguration", "configurationField": "configuration", "description": "The public key provided by Braintree." }
},
"apiProperties": {
+ "addOn": { },
"address": { "customerId": { "kind": "parameter", "displayName": "Customer Id", "group": "common", "label": "", "required": false, "type": "string", "javaType": "java.lang.String", "deprecated": false, "secret": false, "description": "The id of the" }, "id": { "kind": "parameter", "displayName": "Id", "group": "common", "label": "", "required": false, "type": "string", "javaType": "java.lang.String", "deprecated": false, "secret": false, "description": "The id of the" }, "request": { [...]
"clientToken": { "request": { "kind": "parameter", "displayName": "Request", "group": "common", "label": "", "required": false, "type": "object", "javaType": "com.braintreegateway.ClientTokenRequest", "deprecated": false, "secret": false, "description": "" } },
"creditCardVerification": { "id": { "kind": "parameter", "displayName": "Id", "group": "common", "label": "", "required": false, "type": "string", "javaType": "java.lang.String", "deprecated": false, "secret": false, "description": "" }, "query": { "kind": "parameter", "displayName": "Query", "group": "common", "label": "", "required": false, "type": "object", "javaType": "com.braintreegateway.CreditCardVerificationSearchRequest", "deprecated": false, "secret": false, "description": [...]
"customer": { "associationFilterId": { "kind": "parameter", "displayName": "Association Filter Id", "group": "common", "label": "", "required": false, "type": "string", "javaType": "java.lang.String", "deprecated": false, "secret": false, "description": "The id of the association filter to use" }, "id": { "kind": "parameter", "displayName": "Id", "group": "common", "label": "", "required": false, "type": "string", "javaType": "java.lang.String", "deprecated": false, "secret": false, [...]
+ "discount": { },
"dispute": { "content": { "kind": "parameter", "displayName": "Content", "group": "common", "label": "", "required": false, "type": "string", "javaType": "java.lang.String", "deprecated": false, "secret": false, "description": "The content of the text evidence for the dispute" }, "disputeId": { "kind": "parameter", "displayName": "Dispute Id", "group": "common", "label": "", "required": false, "type": "string", "javaType": "java.lang.String", "deprecated": false, "secret": false, "de [...]
"documentUpload": { "request": { "kind": "parameter", "displayName": "Request", "group": "common", "label": "", "required": false, "type": "object", "javaType": "com.braintreegateway.DocumentUploadRequest", "deprecated": false, "secret": false, "description": "" } },
"merchantAccount": { "currencyRequest": { "kind": "parameter", "displayName": "Currency Request", "group": "common", "label": "", "required": false, "type": "object", "javaType": "com.braintreegateway.MerchantAccountCreateForCurrencyRequest", "deprecated": false, "secret": false, "description": "" }, "id": { "kind": "parameter", "displayName": "Id", "group": "common", "label": "", "required": false, "type": "string", "javaType": "java.lang.String", "deprecated": false, "secret": fals [...]
"paymentMethod": { "deleteRequest": { "kind": "parameter", "displayName": "Delete Request", "group": "common", "label": "", "required": false, "type": "object", "javaType": "com.braintreegateway.PaymentMethodDeleteRequest", "deprecated": false, "secret": false, "description": "" }, "grantRequest": { "kind": "parameter", "displayName": "Grant Request", "group": "common", "label": "", "required": false, "type": "object", "javaType": "com.braintreegateway.PaymentMethodGrantRequest", "de [...]
"paymentMethodNonce": { "paymentMethodNonce": { "kind": "parameter", "displayName": "Payment Method Nonce", "group": "common", "label": "", "required": false, "type": "string", "javaType": "java.lang.String", "deprecated": false, "secret": false, "description": "" }, "paymentMethodToken": { "kind": "parameter", "displayName": "Payment Method Token", "group": "common", "label": "", "required": false, "type": "string", "javaType": "java.lang.String", "deprecated": false, "secret": fals [...]
+ "plan": { },
"report": { "request": { "kind": "parameter", "displayName": "Request", "group": "common", "label": "", "required": false, "type": "object", "javaType": "com.braintreegateway.TransactionLevelFeeReportRequest", "deprecated": false, "secret": false, "description": "The request" } },
"settlementBatchSummary": { "groupByCustomField": { "kind": "parameter", "displayName": "Group By Custom Field", "group": "common", "label": "", "required": false, "type": "string", "javaType": "java.lang.String", "deprecated": false, "secret": false, "description": "" }, "settlementDate": { "kind": "parameter", "displayName": "Settlement Date", "group": "common", "label": "", "required": false, "type": "object", "javaType": "java.util.Calendar", "deprecated": false, "secret": false, [...]
"subscription": { "amount": { "kind": "parameter", "displayName": "Amount", "group": "common", "label": "", "required": false, "type": "object", "javaType": "java.math.BigDecimal", "deprecated": false, "secret": false, "description": "" }, "customerId": { "kind": "parameter", "displayName": "Customer Id", "group": "common", "label": "", "required": false, "type": "string", "javaType": "java.lang.String", "deprecated": false, "secret": false, "description": "" }, "id": { "kind": "para [...]
diff --git a/components/camel-braintree/src/main/docs/braintree-component.adoc b/components/camel-braintree/src/main/docs/braintree-component.adoc
index af47ae2..bb0d515 100644
--- a/components/camel-braintree/src/main/docs/braintree-component.adoc
+++ b/components/camel-braintree/src/main/docs/braintree-component.adoc
@@ -127,7 +127,7 @@ with the following path and query parameters:
-=== Query API Parameters (14 APIs):
+=== Query API Parameters (17 APIs):
The Braintree endpoint is an API based component and has conditional parameters based on which API method in use.
The API method is located in the endpoint URI as the apiName path parameter:
@@ -137,7 +137,13 @@ braintree:apiName/methodName
----
+==== apiName: addOn
+
+The addOn method has no API parameters.
+
+
==== apiName: address
+
[width="100%",cols="2,5,^1,2",options="header"]
|===
| Name | Description | Default | Type
@@ -146,14 +152,18 @@ braintree:apiName/methodName
| *request* | The request object | | AddressRequest
|===
+
==== apiName: clientToken
+
[width="100%",cols="2,5,^1,2",options="header"]
|===
| Name | Description | Default | Type
| *request* | | | ClientTokenRequest
|===
+
==== apiName: creditCardVerification
+
[width="100%",cols="2,5,^1,2",options="header"]
|===
| Name | Description | Default | Type
@@ -162,7 +172,9 @@ braintree:apiName/methodName
| *request* | | | CreditCardVerificationRequest
|===
+
==== apiName: customer
+
[width="100%",cols="2,5,^1,2",options="header"]
|===
| Name | Description | Default | Type
@@ -172,7 +184,14 @@ braintree:apiName/methodName
| *request* | The request | | CustomerRequest
|===
+
+==== apiName: discount
+
+The discount method has no API parameters.
+
+
==== apiName: dispute
+
[width="100%",cols="2,5,^1,2",options="header"]
|===
| Name | Description | Default | Type
@@ -186,14 +205,18 @@ braintree:apiName/methodName
| *textEvidenceRequest* | The text evidence request for the dispute | | TextEvidenceRequest
|===
+
==== apiName: documentUpload
+
[width="100%",cols="2,5,^1,2",options="header"]
|===
| Name | Description | Default | Type
| *request* | | | DocumentUploadRequest
|===
+
==== apiName: merchantAccount
+
[width="100%",cols="2,5,^1,2",options="header"]
|===
| Name | Description | Default | Type
@@ -203,7 +226,9 @@ braintree:apiName/methodName
| *request* | | | MerchantAccountRequest
|===
+
==== apiName: paymentMethod
+
[width="100%",cols="2,5,^1,2",options="header"]
|===
| Name | Description | Default | Type
@@ -213,7 +238,9 @@ braintree:apiName/methodName
| *token* | | | String
|===
+
==== apiName: paymentMethodNonce
+
[width="100%",cols="2,5,^1,2",options="header"]
|===
| Name | Description | Default | Type
@@ -222,14 +249,23 @@ braintree:apiName/methodName
| *request* | | | PaymentMethodNonceRequest
|===
+
+==== apiName: plan
+
+The plan method has no API parameters.
+
+
==== apiName: report
+
[width="100%",cols="2,5,^1,2",options="header"]
|===
| Name | Description | Default | Type
| *request* | The request | | TransactionLevelFeeReportRequest
|===
+
==== apiName: settlementBatchSummary
+
[width="100%",cols="2,5,^1,2",options="header"]
|===
| Name | Description | Default | Type
@@ -237,7 +273,9 @@ braintree:apiName/methodName
| *settlementDate* | | | Calendar
|===
+
==== apiName: subscription
+
[width="100%",cols="2,5,^1,2",options="header"]
|===
| Name | Description | Default | Type
@@ -250,7 +288,9 @@ braintree:apiName/methodName
| *subscriptionId* | | | String
|===
+
==== apiName: transaction
+
[width="100%",cols="2,5,^1,2",options="header"]
|===
| Name | Description | Default | Type
@@ -262,7 +302,9 @@ braintree:apiName/methodName
| *request* | The request | | TransactionRequest
|===
+
==== apiName: webhookNotification
+
[width="100%",cols="2,5,^1,2",options="header"]
|===
| Name | Description | Default | Type
diff --git a/tooling/camel-tooling-model/src/main/java/org/apache/camel/tooling/model/JsonMapper.java b/tooling/camel-tooling-model/src/main/java/org/apache/camel/tooling/model/JsonMapper.java
index 9647f22..ae9339e 100644
--- a/tooling/camel-tooling-model/src/main/java/org/apache/camel/tooling/model/JsonMapper.java
+++ b/tooling/camel-tooling-model/src/main/java/org/apache/camel/tooling/model/JsonMapper.java
@@ -21,6 +21,7 @@ import java.nio.charset.StandardCharsets;
import java.nio.file.Files;
import java.nio.file.Path;
import java.util.Collection;
+import java.util.Collections;
import java.util.List;
import java.util.Map;
import java.util.stream.Collectors;
@@ -103,13 +104,17 @@ public final class JsonMapper {
for (Map.Entry<String, Object> entry : mprap.entrySet()) {
String key = entry.getKey();
JsonObject mp = (JsonObject) entry.getValue();
- mp.forEach((k, v) -> {
- String mk = k;
- JsonObject mo = (JsonObject) v;
- ComponentModel.ApiOptionModel option = new ComponentModel.ApiOptionModel();
- parseOption(mo, option, mk);
- model.addApiOption(key, option);
- });
+ if (mp.isEmpty()) {
+ model.getApiOptions().put(key, Collections.EMPTY_LIST);
+ } else {
+ mp.forEach((k, v) -> {
+ String mk = k;
+ JsonObject mo = (JsonObject) v;
+ ComponentModel.ApiOptionModel option = new ComponentModel.ApiOptionModel();
+ parseOption(mo, option, mk);
+ model.addApiOption(key, option);
+ });
+ }
}
}
return model;
diff --git a/tooling/maven/camel-package-maven-plugin/src/main/java/org/apache/camel/maven/packaging/EndpointSchemaGeneratorMojo.java b/tooling/maven/camel-package-maven-plugin/src/main/java/org/apache/camel/maven/packaging/EndpointSchemaGeneratorMojo.java
index e8ff7f7..5b2536f 100644
--- a/tooling/maven/camel-package-maven-plugin/src/main/java/org/apache/camel/maven/packaging/EndpointSchemaGeneratorMojo.java
+++ b/tooling/maven/camel-package-maven-plugin/src/main/java/org/apache/camel/maven/packaging/EndpointSchemaGeneratorMojo.java
@@ -1103,10 +1103,18 @@ public class EndpointSchemaGeneratorMojo extends AbstractGeneratorMojo {
}
}
+ if (apiOption) {
+ // do not check super classes for api options as we only check one level (to include new options and not common)
+ // if there are no options added then add the api name as empty option so we have it marked
+ if (!componentModel.getApiOptions().containsKey(apiName)) {
+ componentModel.getApiOptions().put(apiName, Collections.EMPTY_LIST);
+ }
+ break;
+ }
+
// check super classes which may also have fields
Class<?> superclass = classElement.getSuperclass();
- if (!apiOption && superclass != null) {
- // do not check super classes for api options as we only check one level (to include new options and not common)
+ if (superclass != null) {
classElement = superclass;
} else {
break;
diff --git a/tooling/maven/camel-package-maven-plugin/src/main/resources/endpoint-options.mvel b/tooling/maven/camel-package-maven-plugin/src/main/resources/endpoint-options.mvel
index 1f748e4..44de7e7 100644
--- a/tooling/maven/camel-package-maven-plugin/src/main/resources/endpoint-options.mvel
+++ b/tooling/maven/camel-package-maven-plugin/src/main/resources/endpoint-options.mvel
@@ -43,11 +43,15 @@ The API method is located in the endpoint URI as the @{apiPropertyQualifier} pat
@foreach{api : apiOptions.entrySet()}
==== @{apiPropertyQualifier}: @{api.key}
+@if{api.value.isEmpty()}
+The @{api.key} method has no API parameters.
+@else{}
[width="100%",cols="2,5,^1,2",options="header"]
|===@comment{ Render table cells. If description contains newline, prefix cell with `a`, so the content is rendered with formatting. }
| Name | Description | Default | Type
@foreach{row : api.value}| *@{row.getShortName(30)}* @{row.description.?contains("\n") ? "a" : ""}| @{util.escape(row.description)} | @{row.getShortDefaultValue(20)} | @{row.getShortJavaType()}
@end{}|===
@end{}
+@end{}
@end{}