From e07fce791fe789ff7e0066d7bd31254f1fa8c5b8 Mon Sep 17 00:00:00 2001
From: Shawn <506895667@qq.com>
Date: Wed, 1 Dec 2021 16:31:58 +0800
Subject: [PATCH] feat(connector): add examples to the swagger doc
---
.../emqx_connector/src/emqx_connector_api.erl | 83 ++++++++++++++-----
.../src/emqx_connector_mqtt.erl | 4 +-
.../src/emqx_connector_schema.erl | 11 ++-
.../src/mqtt/emqx_connector_mqtt_schema.erl | 3 +-
.../src/emqx_rule_engine_api.erl | 4 +-
5 files changed, 74 insertions(+), 31 deletions(-)
diff --git a/apps/emqx_connector/src/emqx_connector_api.erl b/apps/emqx_connector/src/emqx_connector_api.erl
index 7e934b997..bc865906f 100644
--- a/apps/emqx_connector/src/emqx_connector_api.erl
+++ b/apps/emqx_connector/src/emqx_connector_api.erl
@@ -38,7 +38,7 @@
catch
error:{invalid_bridge_id, Id0} ->
{400, #{code => 'INVALID_ID', message => <<"invalid_bridge_id: ", Id0/binary,
- ". Bridge ID must be of format 'bridge_type:name'">>}}
+ ". Bridge Ids must be of format {type}:{name}">>}}
end).
namespace() -> "connector".
@@ -53,18 +53,61 @@ error_schema(Code, Message) ->
, {message, mk(string(), #{example => Message})}
].
+put_request_body_schema() ->
+ emqx_dashboard_swagger:schema_with_examples(
+ connector_info(put_req), connector_info_examples()).
+
+post_request_body_schema() ->
+ emqx_dashboard_swagger:schema_with_examples(
+ connector_info(post_req), connector_info_examples()).
+
+get_response_body_schema() ->
+ emqx_dashboard_swagger:schema_with_example(
+ connector_info(), connector_info_examples()).
+
connector_info() ->
+ connector_info(resp).
+
+connector_info(resp) ->
hoconsc:union([ ref(emqx_connector_schema, "mqtt_connector_info")
- ]).
-
-connector_test_info() ->
- hoconsc:union([ ref(emqx_connector_schema, "mqtt_connector_test_info")
- ]).
-
-connector_req() ->
+ ]);
+connector_info(put_req) ->
+ hoconsc:union([ ref(emqx_connector_mqtt_schema, "connector")
+ ]);
+connector_info(post_req) ->
hoconsc:union([ ref(emqx_connector_schema, "mqtt_connector")
]).
+connector_info_array_example() ->
+ [Config || #{value := Config} <- maps:values(connector_info_examples())].
+
+connector_info_examples() ->
+ #{
+ mqtt => #{
+ summary => <<"MQTT Bridge">>,
+ value => mqtt_info_example()
+ }
+ }.
+
+mqtt_info_example() ->
+ #{
+ type => <<"mqtt">>,
+ server => <<"127.0.0.1:1883">>,
+ reconnect_interval => <<"30s">>,
+ proto_ver => <<"v4">>,
+ bridge_mode => true,
+ username => <<"foo">>,
+ password => <<"bar">>,
+ clientid => <<"foo">>,
+ clean_start => true,
+ keepalive => <<"300s">>,
+ retry_interval => <<"30s">>,
+ max_inflight => 100,
+ ssl => #{
+ enable => false
+ }
+ }.
+
param_path_id() ->
[{id, mk(binary(), #{in => path, example => <<"mqtt:my_mqtt_connector">>})}].
@@ -74,9 +117,9 @@ schema("/connectors_test") ->
post => #{
tags => [<<"connectors">>],
description => <<"Test creating a new connector by given Id
"
- "The ID must be of format 'type:name'">>,
+ "The ID must be of format '{type}:{name}'">>,
summary => <<"Test creating connector">>,
- requestBody => connector_test_info(),
+ requestBody => post_request_body_schema(),
responses => #{
200 => <<"Test connector OK">>,
400 => error_schema('TEST_FAILED', "connector test failed")
@@ -92,17 +135,19 @@ schema("/connectors") ->
description => <<"List all connectors">>,
summary => <<"List connectors">>,
responses => #{
- 200 => mk(array(connector_info()), #{desc => "List of connectors"})
+ 200 => emqx_dashboard_swagger:schema_with_example(
+ array(connector_info()),
+ connector_info_array_example())
}
},
post => #{
tags => [<<"connectors">>],
description => <<"Create a new connector by given Id
"
- "The ID must be of format 'type:name'">>,
+ "The ID must be of format '{type}:{name}'">>,
summary => <<"Create connector">>,
- requestBody => connector_info(),
+ requestBody => post_request_body_schema(),
responses => #{
- 201 => connector_info(),
+ 201 => get_response_body_schema(),
400 => error_schema('ALREADY_EXISTS', "connector already exists")
}
}
@@ -117,7 +162,7 @@ schema("/connectors/:id") ->
summary => <<"Get connector">>,
parameters => param_path_id(),
responses => #{
- 200 => connector_info(),
+ 200 => get_response_body_schema(),
404 => error_schema('NOT_FOUND', "Connector not found")
}
},
@@ -126,9 +171,9 @@ schema("/connectors/:id") ->
description => <<"Update an existing connector by Id">>,
summary => <<"Update connector">>,
parameters => param_path_id(),
- requestBody => connector_req(),
+ requestBody => put_request_body_schema(),
responses => #{
- 200 => <<"Update connector successfully">>,
+ 200 => get_response_body_schema(),
400 => error_schema('UPDATE_FAIL', "Update failed"),
404 => error_schema('NOT_FOUND', "Connector not found")
}},
@@ -143,8 +188,8 @@ schema("/connectors/:id") ->
}}
}.
-'/connectors_test'(post, #{body := #{<<"bridge_type">> := ConnType} = Params}) ->
- case emqx_connector:create_dry_run(ConnType, maps:remove(<<"bridge_type">>, Params)) of
+'/connectors_test'(post, #{body := #{<<"type">> := ConnType} = Params}) ->
+ case emqx_connector:create_dry_run(ConnType, maps:remove(<<"type">>, Params)) of
ok -> {200};
{error, Error} ->
{400, error_msg('BAD_ARG', Error)}
diff --git a/apps/emqx_connector/src/emqx_connector_mqtt.erl b/apps/emqx_connector/src/emqx_connector_mqtt.erl
index 1acd8b298..190456262 100644
--- a/apps/emqx_connector/src/emqx_connector_mqtt.erl
+++ b/apps/emqx_connector/src/emqx_connector_mqtt.erl
@@ -100,7 +100,7 @@ on_start(InstId, Conf) ->
BasicConf = basic_config(Conf),
BridgeConf = BasicConf#{
name => InstanceId,
- clientid => clientid(InstanceId),
+ clientid => clientid(maps:get(clientid, Conf, InstanceId)),
subscriptions => make_sub_confs(maps:get(ingress, Conf, undefined)),
forwards => make_forward_confs(maps:get(egress, Conf, undefined))
},
@@ -190,4 +190,4 @@ basic_config(#{
}.
clientid(Id) ->
- list_to_binary(lists:concat([Id, ":", node()])).
+ unicode:characters_to_binary([Id, ":", atom_to_list(node())], utf8).
diff --git a/apps/emqx_connector/src/emqx_connector_schema.erl b/apps/emqx_connector/src/emqx_connector_schema.erl
index 3caf2b595..518d4e62d 100644
--- a/apps/emqx_connector/src/emqx_connector_schema.erl
+++ b/apps/emqx_connector/src/emqx_connector_schema.erl
@@ -22,14 +22,13 @@ fields("connectors") ->
];
fields("mqtt_connector") ->
- emqx_connector_mqtt_schema:fields("connector");
+ [ {type, sc(mqtt, #{desc => "The Connector Type"})}
+ %, {name, sc(binary(), #{desc => "The Connector Name"})}
+ ]
+ ++ emqx_connector_mqtt_schema:fields("connector");
fields("mqtt_connector_info") ->
- [{id, sc(binary(), #{desc => "The connector Id"})}]
- ++ fields("mqtt_connector");
-
-fields("mqtt_connector_test_info") ->
- [{bridge_type, sc(mqtt, #{desc => "The Bridge Type"})}]
+ [{id, sc(binary(), #{desc => "The connector Id", example => "mqtt:foo"})}]
++ fields("mqtt_connector").
sc(Type, Meta) -> hoconsc:mk(Type, Meta).
diff --git a/apps/emqx_connector/src/mqtt/emqx_connector_mqtt_schema.erl b/apps/emqx_connector/src/mqtt/emqx_connector_mqtt_schema.erl
index 6436a4c96..415c6fa1a 100644
--- a/apps/emqx_connector/src/mqtt/emqx_connector_mqtt_schema.erl
+++ b/apps/emqx_connector/src/mqtt/emqx_connector_mqtt_schema.erl
@@ -66,8 +66,7 @@ fields("connector") ->
})}
, {clientid,
sc(binary(),
- #{ default => "emqx_${nodename}"
- , desc => "The clientid of the MQTT protocol"
+ #{ desc => "The clientid of the MQTT protocol"
})}
, {clean_start,
sc(boolean(),
diff --git a/apps/emqx_rule_engine/src/emqx_rule_engine_api.erl b/apps/emqx_rule_engine/src/emqx_rule_engine_api.erl
index 9e341b388..2629a33e7 100644
--- a/apps/emqx_rule_engine/src/emqx_rule_engine_api.erl
+++ b/apps/emqx_rule_engine/src/emqx_rule_engine_api.erl
@@ -92,7 +92,7 @@ api_rules_crud() ->
<<"200">> =>
emqx_mgmt_util:schema(resp_schema(), <<"Get rule successfully">>)}},
put => #{
- description => <<"Create or update a rule by given Id to all nodes in the cluster">>,
+ description => <<"Update a rule by given Id to all nodes in the cluster">>,
parameters => [param_path_id()],
'requestBody' => emqx_mgmt_util:schema(put_req_schema(), <<"Rule parameters">>),
responses => #{
@@ -100,7 +100,7 @@ api_rules_crud() ->
emqx_mgmt_util:error_schema(<<"Invalid Parameters">>, ['BAD_ARGS']),
<<"200">> =>
emqx_mgmt_util:schema(resp_schema(),
- <<"Create or update rule successfully">>)}},
+ <<"Update rule successfully">>)}},
delete => #{
description => <<"Delete a rule by given Id from all nodes in the cluster">>,
parameters => [param_path_id()],