[Doc] add explanations for REST API (function/source/sink) (#13569)
diff --git a/pulsar-broker/src/main/java/org/apache/pulsar/broker/admin/impl/FunctionsBase.java b/pulsar-broker/src/main/java/org/apache/pulsar/broker/admin/impl/FunctionsBase.java
index bb19dae..f1c4c10 100644
--- a/pulsar-broker/src/main/java/org/apache/pulsar/broker/admin/impl/FunctionsBase.java
+++ b/pulsar-broker/src/main/java/org/apache/pulsar/broker/admin/impl/FunctionsBase.java
@@ -79,7 +79,10 @@
final @FormDataParam("data") FormDataContentDisposition fileDetail,
final @FormDataParam("url") String functionPkgUrl,
@ApiParam(
- value = "A JSON value presenting configuration payload of a Pulsar Function."
+ value = "You can submit a function (in any languages that you are familiar with) \n"
+ + "to a Pulsar cluster. Follow the steps below. \n"
+ + "1. Create a JSON object using some of the following parameters.\n"
+ + "A JSON value presenting configuration payload of a Pulsar Function.\n"
+ " An example of the expected Pulsar Function can be found here.\n"
+ "- **autoAck**\n"
+ " Whether or not the framework acknowledges messages automatically.\n"
@@ -163,23 +166,37 @@
+ " SecretProviderConfigurator.getSecretObjectType() method. \n"
+ "- **cleanupSubscription**\n"
+ " Whether the subscriptions of a Pulsar Function created or used should be deleted"
- + " when the Pulsar Function is deleted.\n",
+ + " when the Pulsar Function is deleted.\n"
+ + "2. Encapsulate the JSON object to a multipart object.",
examples = @Example(
- value = @ExampleProperty(
- mediaType = MediaType.APPLICATION_JSON,
- value = "{\n"
- + " \"inputs\": persistent://public/default/input-topic,\n"
- + " \"parallelism\": 4\n"
- + " \"output\": persistent://public/default/output-topic\n"
- + " \"log-topic\": persistent://public/default/log-topic\n"
- + " \"classname\": org.example.test.ExclamationFunction\n"
- + " \"jar\": java-function-1.0-SNAPSHOT.jar\n"
+ value = {
+ @ExampleProperty(
+ mediaType = MediaType.TEXT_PLAIN,
+ value = " Example \n"
+ + "\n"
+ + " 1. Create a JSON object. \n"
+ + "\n"
+ + "{\n"
+ + "\t\"inputs\": \"persistent://public/default/input-topic\",\n"
+ + "\t\"parallelism\": \"4\",\n"
+ + "\t\"output\": \"persistent://public/default/output-topic\",\n"
+ + "\t\"log-topic\": \"persistent://public/default/log-topic\",\n"
+ + "\t\"classname\": \"org.example.test.ExclamationFunction\",\n"
+ + "\t\"jar\": \"java-function-1.0-SNAPSHOT.jar\"\n"
+ "}\n"
- )
+ + "\n"
+ + "\n"
+ + "2. Encapsulate the JSON object to a multipart object (in Python). \n"
+ + "\n"
+ + "from requests_toolbelt.multipart.encoder import MultipartEncoder \n"
+ + "mp_encoder = MultipartEncoder( \n"
+ + "\t[('functionConfig', "
+ + "(None, json.dumps(config), 'application/json'))])\n"
+ )
+ }
)
)
final @FormDataParam("functionConfig") FunctionConfig functionConfig) {
-
functions().registerFunction(tenant, namespace, functionName, uploadedInputStream, fileDetail,
functionPkgUrl, functionConfig, clientAppId(), clientAuthData());
}
diff --git a/pulsar-broker/src/main/java/org/apache/pulsar/broker/admin/impl/SinksBase.java b/pulsar-broker/src/main/java/org/apache/pulsar/broker/admin/impl/SinksBase.java
index e2d3a2d..d450164 100644
--- a/pulsar-broker/src/main/java/org/apache/pulsar/broker/admin/impl/SinksBase.java
+++ b/pulsar-broker/src/main/java/org/apache/pulsar/broker/admin/impl/SinksBase.java
@@ -75,7 +75,10 @@
final @FormDataParam("data") FormDataContentDisposition fileDetail,
final @FormDataParam("url") String sinkPkgUrl,
@ApiParam(value =
- "A JSON value presenting config payload of a Pulsar Sink."
+ "You can submit a sink (in any languages that you are familiar with) "
+ + "to a Pulsar cluster. Follow the steps below.\n"
+ + "1. Create a JSON object using some of the following parameters.\n"
+ + "A JSON value presenting config payload of a Pulsar Sink."
+ " All available configuration options are:\n"
+ "- **classname**\n"
+ " The class name of a Pulsar Sink if"
@@ -136,19 +139,36 @@
+ " Boolean denotes whether the subscriptions the functions"
+ " created/used should be deleted when the functions is deleted\n"
+ "- **runtimeFlags**\n"
- + " Any flags that you want to pass to the runtime as a single string\n",
+ + " Any flags that you want to pass to the runtime as a single string\n"
+ + "2. Encapsulate the JSON object to a multipart object.",
examples = @Example(
- value = @ExampleProperty(
- mediaType = MediaType.APPLICATION_JSON,
- value = "{\n"
+ value = {
+ @ExampleProperty(
+ mediaType = MediaType.TEXT_PLAIN,
+ value = "Example \n"
+ + "\n"
+ + " 1. Create a JSON object. \n"
+ + "\n"
+ + "{\n"
+ "\t\"classname\": \"org.example.MySinkTest\",\n"
+ "\t\"inputs\": ["
+ "\"persistent://public/default/sink-input\"],\n"
+ "\t\"processingGuarantees\": \"EFFECTIVELY_ONCE\",\n"
- + "\t\"parallelism\": 10\n"
- + "}"
- )
- )
+ + "\t\"parallelism\": \"10\"\n"
+ + "}\n"
+ + "\n"
+ + "\n"
+ + "2. Encapsulate the JSON object to a multipart object "
+ + "(in Python).\n"
+ + "\n"
+ + "from requests_toolbelt.multipart.encoder import "
+ + "MultipartEncoder \n"
+ + "mp_encoder = MultipartEncoder( \n"
+ + "\t[('sinkConfig', "
+ + "(None, json.dumps(config), 'application/json'))])\n"
+ )
+ }
+ )
)
final @FormDataParam("sinkConfig") SinkConfig sinkConfig) {
sinks().registerSink(tenant, namespace, sinkName, uploadedInputStream, fileDetail,
diff --git a/pulsar-broker/src/main/java/org/apache/pulsar/broker/admin/impl/SourcesBase.java b/pulsar-broker/src/main/java/org/apache/pulsar/broker/admin/impl/SourcesBase.java
index 8779519..b4ba332 100644
--- a/pulsar-broker/src/main/java/org/apache/pulsar/broker/admin/impl/SourcesBase.java
+++ b/pulsar-broker/src/main/java/org/apache/pulsar/broker/admin/impl/SourcesBase.java
@@ -76,8 +76,11 @@
final @FormDataParam("data") InputStream uploadedInputStream,
final @FormDataParam("data") FormDataContentDisposition fileDetail,
final @FormDataParam("url") String sourcePkgUrl,
- @ApiParam(
- value = "A JSON value presenting configuration payload of a Pulsar Source."
+ @ApiParam(value =
+ "You can submit a source (in any languages that you are familiar with) to a Pulsar cluster. "
+ + "Follow the steps below.\n"
+ + "1. Create a JSON object using some of the following parameters.\n"
+ + "A JSON value presenting configuration payload of a Pulsar Source."
+ " An example of the expected functions can be found here.\n"
+ "- **classname**\n"
+ " The class name of a Pulsar Source if archive is file-url-path (file://).\n"
@@ -111,20 +114,33 @@
+ " [http/https/file (file protocol assumes that file already exists on worker host)] "
+ " from which worker can download the package.\n"
+ "- **runtimeFlags**\n"
- + " Any flags that you want to pass to the runtime.\n",
+ + " Any flags that you want to pass to the runtime.\n"
+ + "2. Encapsulate the JSON object to a multipart object.",
examples = @Example(
value = @ExampleProperty(
- mediaType = MediaType.APPLICATION_JSON,
- value = "{\n"
- + " \"tenant\": public\n"
- + " \"namespace\": default\n"
- + " \"name\": pulsar-io-mysql\n"
- + " \"className\": TestSourceMysql\n"
- + " \"topicName\": pulsar-io-mysql\n"
- + " \"parallelism\": 1\n"
- + " \"archive\": /connectors/pulsar-io-mysql-0.0.1.nar\n"
- + " \"schemaType\": avro\n"
+ mediaType = MediaType.TEXT_PLAIN,
+ value = " Example \n"
+ + "\n"
+ + "1. Create a JSON object. \n"
+ + "\n"
+ + "{\n"
+ + "\t\"tenant\": \"public\",\n"
+ + "\t\"namespace\": \"default\",\n"
+ + "\t\"name\": \"pulsar-io-mysql\",\n"
+ + "\t\"className\": \"TestSourceMysql\",\n"
+ + "\t\"topicName\": \"pulsar-io-mysql\",\n"
+ + "\t\"parallelism\": \"1\",\n"
+ + "\t\"archive\": \"/connectors/pulsar-io-mysql-0.0.1.nar\",\n"
+ + "\t\"schemaType\": \"avro\"\n"
+ "}\n"
+ + "\n"
+ + "\n"
+ + "2. Encapsulate the JSON object to a multipart object (in Python). \n"
+ + "\n"
+ + "from requests_toolbelt.multipart.encoder import MultipartEncoder \n"
+ + "mp_encoder = MultipartEncoder( \n"
+ + "\t[('sourceConfig', "
+ + "(None, json.dumps(config), 'application/json'))])\n"
)
)
)
diff --git a/site2/website/package.json b/site2/website/package.json
index 7527ee6..d22e8a5 100644
--- a/site2/website/package.json
+++ b/site2/website/package.json
@@ -1,7 +1,7 @@
{
"scripts": {
"examples": "docusaurus-examples",
- "start": "docusaurus-start",
+ "start": "NODE_OPTIONS=--max_old_space_size=20480 docusaurus-start",
"build": "docusaurus-build",
"publish-gh-pages": "docusaurus-publish",
"write-translations": "docusaurus-write-translations",
