refactor(emqx_connector_info): improve documentation and type specs

apps/emqx_bridge_azure_event_hub/src/emqx_bridge_azure_event_hub.erl

@@ -3,6 +3,8 @@
 %%--------------------------------------------------------------------
 -module(emqx_bridge_azure_event_hub).
 
+-behaviour(emqx_connector_examples).
+
 -include_lib("typerefl/include/types.hrl").
 -include_lib("hocon/include/hoconsc.hrl").
 

apps/emqx_bridge_cassandra/src/emqx_bridge_cassandra.erl

@@ -3,6 +3,8 @@
 %%--------------------------------------------------------------------
 -module(emqx_bridge_cassandra).
 
+-behaviour(emqx_connector_examples).
+
 -include_lib("typerefl/include/types.hrl").
 -include_lib("hocon/include/hoconsc.hrl").
 -include_lib("emqx_bridge/include/emqx_bridge.hrl").

apps/emqx_bridge_clickhouse/src/emqx_bridge_clickhouse.erl

@@ -3,6 +3,8 @@
 %%--------------------------------------------------------------------
 -module(emqx_bridge_clickhouse).
 
+-behaviour(emqx_connector_examples).
+
 -include_lib("typerefl/include/types.hrl").
 -include_lib("hocon/include/hoconsc.hrl").
 -include_lib("emqx_resource/include/emqx_resource.hrl").

apps/emqx_bridge_confluent/src/emqx_bridge_confluent_producer.erl

@@ -3,6 +3,8 @@
 %%--------------------------------------------------------------------
 -module(emqx_bridge_confluent_producer).
 
+-behaviour(emqx_connector_examples).
+
 -include_lib("typerefl/include/types.hrl").
 -include_lib("hocon/include/hoconsc.hrl").
 

apps/emqx_bridge_dynamo/src/emqx_bridge_dynamo.erl

@@ -3,6 +3,8 @@
 %%--------------------------------------------------------------------
 -module(emqx_bridge_dynamo).
 
+-behaviour(emqx_connector_examples).
+
 -include_lib("typerefl/include/types.hrl").
 -include_lib("hocon/include/hoconsc.hrl").
 -include_lib("emqx_bridge/include/emqx_bridge.hrl").

apps/emqx_bridge_es/src/emqx_bridge_es_connector.erl

@@ -3,6 +3,8 @@
 %%--------------------------------------------------------------------
 -module(emqx_bridge_es_connector).
 
+-behaviour(emqx_connector_examples).
+
 -behaviour(emqx_resource).
 
 -include("emqx_bridge_es.hrl").

apps/emqx_bridge_gcp_pubsub/src/emqx_bridge_gcp_pubsub_consumer_schema.erl

@@ -4,6 +4,8 @@
 
 -module(emqx_bridge_gcp_pubsub_consumer_schema).
 
+-behaviour(emqx_connector_examples).
+
 -import(hoconsc, [mk/2, ref/2]).
 
 -include_lib("typerefl/include/types.hrl").

apps/emqx_bridge_gcp_pubsub/src/emqx_bridge_gcp_pubsub_producer_schema.erl

@@ -4,6 +4,8 @@
 
 -module(emqx_bridge_gcp_pubsub_producer_schema).
 
+-behaviour(emqx_connector_examples).
+
 -import(hoconsc, [mk/2, ref/2]).
 
 -include_lib("typerefl/include/types.hrl").

apps/emqx_bridge_greptimedb/src/emqx_bridge_greptimedb.erl

@@ -3,6 +3,8 @@
 %%--------------------------------------------------------------------
 -module(emqx_bridge_greptimedb).
 
+-behaviour(emqx_connector_examples).
+
 -include_lib("emqx/include/logger.hrl").
 -include_lib("emqx_connector/include/emqx_connector.hrl").
 -include_lib("typerefl/include/types.hrl").

apps/emqx_bridge_hstreamdb/src/emqx_bridge_hstreamdb.erl

@@ -3,6 +3,8 @@
 %%--------------------------------------------------------------------
 -module(emqx_bridge_hstreamdb).
 
+-behaviour(emqx_connector_examples).
+
 -include_lib("typerefl/include/types.hrl").
 -include_lib("hocon/include/hoconsc.hrl").
 -include("emqx_bridge_hstreamdb.hrl").

apps/emqx_bridge_http/src/emqx_bridge_http_schema.erl

@@ -15,6 +15,8 @@
 %%--------------------------------------------------------------------
 -module(emqx_bridge_http_schema).
 
+-behaviour(emqx_connector_examples).
+
 -include_lib("typerefl/include/types.hrl").
 -include_lib("hocon/include/hoconsc.hrl").
 

apps/emqx_bridge_influxdb/src/emqx_bridge_influxdb.erl

@@ -3,6 +3,8 @@
 %%--------------------------------------------------------------------
 -module(emqx_bridge_influxdb).
 
+-behaviour(emqx_connector_examples).
+
 -include_lib("emqx/include/logger.hrl").
 -include_lib("emqx_connector/include/emqx_connector.hrl").
 -include_lib("typerefl/include/types.hrl").

apps/emqx_bridge_iotdb/src/emqx_bridge_iotdb_connector.erl

@@ -3,6 +3,8 @@
 %%--------------------------------------------------------------------
 -module(emqx_bridge_iotdb_connector).
 
+-behaviour(emqx_connector_examples).
+
 -behaviour(emqx_resource).
 
 -include("emqx_bridge_iotdb.hrl").

apps/emqx_bridge_kafka/src/emqx_bridge_kafka.erl

@@ -3,6 +3,8 @@
 %%--------------------------------------------------------------------
 -module(emqx_bridge_kafka).
 
+-behaviour(emqx_connector_examples).
+
 -include_lib("typerefl/include/types.hrl").
 -include_lib("hocon/include/hoconsc.hrl").
 

apps/emqx_bridge_kafka/src/emqx_bridge_kafka_consumer_schema.erl

@@ -3,6 +3,8 @@
 %%--------------------------------------------------------------------
 -module(emqx_bridge_kafka_consumer_schema).
 
+-behaviour(emqx_connector_examples).
+
 -include_lib("typerefl/include/types.hrl").
 -include_lib("hocon/include/hoconsc.hrl").
 

apps/emqx_bridge_kinesis/src/emqx_bridge_kinesis.erl

@@ -4,6 +4,8 @@
 
 -module(emqx_bridge_kinesis).
 
+-behaviour(emqx_connector_examples).
+
 -include_lib("typerefl/include/types.hrl").
 -include_lib("hocon/include/hoconsc.hrl").
 

apps/emqx_bridge_matrix/src/emqx_bridge_matrix.erl

@@ -3,6 +3,8 @@
 %%--------------------------------------------------------------------
 -module(emqx_bridge_matrix).
 
+-behaviour(emqx_connector_examples).
+
 -include_lib("hocon/include/hoconsc.hrl").
 
 -export([

apps/emqx_bridge_mongodb/src/emqx_bridge_mongodb.erl

@@ -3,6 +3,8 @@
 %%--------------------------------------------------------------------
 -module(emqx_bridge_mongodb).
 
+-behaviour(emqx_connector_examples).
+
 -include_lib("typerefl/include/types.hrl").
 -include_lib("hocon/include/hoconsc.hrl").
 

apps/emqx_bridge_mqtt/src/emqx_bridge_mqtt_connector_schema.erl

@@ -16,6 +16,8 @@
 
 -module(emqx_bridge_mqtt_connector_schema).
 
+-behaviour(emqx_connector_examples).
+
 -include_lib("typerefl/include/types.hrl").
 -include_lib("hocon/include/hoconsc.hrl").
 -include_lib("emqx/include/logger.hrl").

apps/emqx_bridge_mysql/src/emqx_bridge_mysql.erl

@@ -3,6 +3,8 @@
 %%--------------------------------------------------------------------
 -module(emqx_bridge_mysql).
 
+-behaviour(emqx_connector_examples).
+
 -include_lib("typerefl/include/types.hrl").
 -include_lib("hocon/include/hoconsc.hrl").
 -include_lib("emqx_resource/include/emqx_resource.hrl").

apps/emqx_bridge_opents/src/emqx_bridge_opents_connector.erl

@@ -4,6 +4,8 @@
 
 -module(emqx_bridge_opents_connector).
 
+-behaviour(emqx_connector_examples).
+
 -behaviour(emqx_resource).
 
 -include_lib("emqx_resource/include/emqx_resource.hrl").

apps/emqx_bridge_oracle/src/emqx_bridge_oracle.erl

@@ -3,6 +3,8 @@
 %%--------------------------------------------------------------------
 -module(emqx_bridge_oracle).
 
+-behaviour(emqx_connector_examples).
+
 -include_lib("typerefl/include/types.hrl").
 -include_lib("hocon/include/hoconsc.hrl").
 -include_lib("emqx_bridge/include/emqx_bridge.hrl").

apps/emqx_bridge_pulsar/src/emqx_bridge_pulsar_connector_schema.erl

@@ -3,6 +3,8 @@
 %%--------------------------------------------------------------------
 -module(emqx_bridge_pulsar_connector_schema).
 
+-behaviour(emqx_connector_examples).
+
 -export([namespace/0, roots/0, fields/1, desc/1]).
 -export([connector_examples/1, connector_example_values/0]).
 

apps/emqx_bridge_rabbitmq/src/emqx_bridge_rabbitmq_connector_schema.erl

@@ -16,6 +16,8 @@
 
 -module(emqx_bridge_rabbitmq_connector_schema).
 
+-behaviour(emqx_connector_examples).
+
 -include_lib("typerefl/include/types.hrl").
 -include_lib("hocon/include/hoconsc.hrl").
 

apps/emqx_bridge_redis/src/emqx_bridge_redis_schema.erl

@@ -4,6 +4,8 @@
 
 -module(emqx_bridge_redis_schema).
 
+-behaviour(emqx_connector_examples).
+
 -include_lib("typerefl/include/types.hrl").
 -include_lib("hocon/include/hoconsc.hrl").
 -define(TYPE, redis).

apps/emqx_bridge_rocketmq/src/emqx_bridge_rocketmq.erl

@@ -3,6 +3,8 @@
 %%--------------------------------------------------------------------
 -module(emqx_bridge_rocketmq).
 
+-behaviour(emqx_connector_examples).
+
 -include_lib("typerefl/include/types.hrl").
 -include_lib("hocon/include/hoconsc.hrl").
 -include_lib("emqx_bridge/include/emqx_bridge.hrl").

apps/emqx_bridge_s3/src/emqx_bridge_s3.erl

@@ -4,6 +4,8 @@
 
 -module(emqx_bridge_s3).
 
+-behaviour(emqx_connector_examples).
+
 -include_lib("typerefl/include/types.hrl").
 -include_lib("hocon/include/hoconsc.hrl").
 -include("emqx_bridge_s3.hrl").

apps/emqx_bridge_sqlserver/src/emqx_bridge_sqlserver.erl

@@ -3,6 +3,8 @@
 %%--------------------------------------------------------------------
 -module(emqx_bridge_sqlserver).
 
+-behaviour(emqx_connector_examples).
+
 -include_lib("typerefl/include/types.hrl").
 -include_lib("hocon/include/hoconsc.hrl").
 -include_lib("emqx_bridge/include/emqx_bridge.hrl").

apps/emqx_bridge_syskeeper/src/emqx_bridge_syskeeper_connector.erl

@@ -4,6 +4,8 @@
 
 -module(emqx_bridge_syskeeper_connector).
 
+-behaviour(emqx_connector_examples).
+
 -behaviour(emqx_resource).
 
 -include_lib("emqx_resource/include/emqx_resource.hrl").

apps/emqx_bridge_syskeeper/src/emqx_bridge_syskeeper_proxy.erl

@@ -3,6 +3,8 @@
 %%--------------------------------------------------------------------
 -module(emqx_bridge_syskeeper_proxy).
 
+-behaviour(emqx_connector_examples).
+
 -include_lib("typerefl/include/types.hrl").
 -include_lib("hocon/include/hoconsc.hrl").
 -include_lib("emqx_bridge/include/emqx_bridge.hrl").

apps/emqx_bridge_tdengine/src/emqx_bridge_tdengine_connector.erl

@@ -4,6 +4,8 @@
 
 -module(emqx_bridge_tdengine_connector).
 
+-behaviour(emqx_connector_examples).
+
 -behaviour(emqx_resource).
 
 -include_lib("typerefl/include/types.hrl").

apps/emqx_bridge_timescale/src/emqx_bridge_timescale.erl

@@ -3,6 +3,8 @@
 %%--------------------------------------------------------------------
 -module(emqx_bridge_timescale).
 
+-behaviour(emqx_connector_examples).
+
 -include_lib("hocon/include/hoconsc.hrl").
 
 -export([

apps/emqx_connector/src/emqx_connector_examples.erl

@@ -0,0 +1,22 @@
+%%--------------------------------------------------------------------
+%% Copyright (c) 2023-2024 EMQ Technologies Co., Ltd. All Rights Reserved.
+%%
+%% Licensed under the Apache License, Version 2.0 (the "License");
+%% you may not use this file except in compliance with the License.
+%% You may obtain a copy of the License at
+%%
+%%     http://www.apache.org/licenses/LICENSE-2.0
+%%
+%% Unless required by applicable law or agreed to in writing, software
+%% distributed under the License is distributed on an "AS IS" BASIS,
+%% WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+%% See the License for the specific language governing permissions and
+%% limitations under the License.
+%%--------------------------------------------------------------------
+
+-module(emqx_connector_examples).
+
+%% Should return examples for the connector HTTP API. One can use the helper
+%% function emqx_connector_schema:connector_values/3 to generate these
+%% examples. See emqx_bridge_oracle:connector_examples/1 for an example.
+-callback connector_examples(Method :: get | post | put) -> [map()].

apps/emqx_connector/src/emqx_connector_info.erl

@@ -31,15 +31,33 @@
 
 -export([clean_cache/0]).
 
+%% The type name for the conncector
 -callback type_name() -> atom().
+
+%% The action, source and bridge_v1 types that are using the connector
 -callback bridge_types() -> [atom()].
+
+%% The implementation of the emqx_resource behavior for the connector
 -callback resource_callback_module() -> atom().
+
+%% The module containing implementation of the emqx_connector_examples behavior.
 -callback schema_module() -> atom().
+
+%% The hocon configuration schema for the connector. This schema should usually
+%% contain a reference to the schema_module(). See
+%% emqx_bridge_oracle_connector_info:config_schema/0 for an example.
 -callback config_schema() -> term().
--callback api_schema([char()]) -> term().
+
+%% Should return the hocon configuration schema for the connector HTTP method.
+%% Note that one can use the helper functions emqx_connector_schema:api_ref/3
+%% and emqx_connector_schema:api_fields/3 to implement this. See
+%% emqx_bridge_oracle_connector_info:api_schema/1 and the corresponding clause
+%% in emqx_bridge_oracle:fields/1 for an example. Method is "get", "post" or "put".
+-callback api_schema(Method :: string()) -> term().
+
 %% Optional callback that should return a module with an exported
 %% connector_config/2 function. If present this function will be used to
-%% transfrom the connector configuration. See the callback connector_config/2
+%% transform the connector configuration. See the callback connector_config/2
 %% in emqx_connector_resource for more information.
 -callback config_transform_module() -> atom().
 
@@ -48,7 +66,7 @@
 ]).
 
 %% ====================================================================
-%% HardCoded list of info modules for connectors
+%% Hard coded list of info modules for connectors
 %% TODO: Remove this list once we have made sure that all relevants
 %% apps are loaded before this module is called.
 %% ====================================================================

apps/emqx_postgresql/src/schema/emqx_postgresql_connector_schema.erl

@@ -16,6 +16,8 @@
 
 -module(emqx_postgresql_connector_schema).
 
+-behaviour(emqx_connector_examples).
+
 -include_lib("hocon/include/hoconsc.hrl").
 -include_lib("emqx_postgresql/include/emqx_postgresql.hrl").