feat(connector): add examples to the swagger doc
This commit is contained in:
parent
4eef9a5bac
commit
e07fce791f
|
@ -38,7 +38,7 @@
|
||||||
catch
|
catch
|
||||||
error:{invalid_bridge_id, Id0} ->
|
error:{invalid_bridge_id, Id0} ->
|
||||||
{400, #{code => 'INVALID_ID', message => <<"invalid_bridge_id: ", Id0/binary,
|
{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).
|
end).
|
||||||
|
|
||||||
namespace() -> "connector".
|
namespace() -> "connector".
|
||||||
|
@ -53,18 +53,61 @@ error_schema(Code, Message) ->
|
||||||
, {message, mk(string(), #{example => 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() ->
|
||||||
|
connector_info(resp).
|
||||||
|
|
||||||
|
connector_info(resp) ->
|
||||||
hoconsc:union([ ref(emqx_connector_schema, "mqtt_connector_info")
|
hoconsc:union([ ref(emqx_connector_schema, "mqtt_connector_info")
|
||||||
]).
|
]);
|
||||||
|
connector_info(put_req) ->
|
||||||
connector_test_info() ->
|
hoconsc:union([ ref(emqx_connector_mqtt_schema, "connector")
|
||||||
hoconsc:union([ ref(emqx_connector_schema, "mqtt_connector_test_info")
|
]);
|
||||||
]).
|
connector_info(post_req) ->
|
||||||
|
|
||||||
connector_req() ->
|
|
||||||
hoconsc:union([ ref(emqx_connector_schema, "mqtt_connector")
|
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() ->
|
param_path_id() ->
|
||||||
[{id, mk(binary(), #{in => path, example => <<"mqtt:my_mqtt_connector">>})}].
|
[{id, mk(binary(), #{in => path, example => <<"mqtt:my_mqtt_connector">>})}].
|
||||||
|
|
||||||
|
@ -74,9 +117,9 @@ schema("/connectors_test") ->
|
||||||
post => #{
|
post => #{
|
||||||
tags => [<<"connectors">>],
|
tags => [<<"connectors">>],
|
||||||
description => <<"Test creating a new connector by given Id <br>"
|
description => <<"Test creating a new connector by given Id <br>"
|
||||||
"The ID must be of format 'type:name'">>,
|
"The ID must be of format '{type}:{name}'">>,
|
||||||
summary => <<"Test creating connector">>,
|
summary => <<"Test creating connector">>,
|
||||||
requestBody => connector_test_info(),
|
requestBody => post_request_body_schema(),
|
||||||
responses => #{
|
responses => #{
|
||||||
200 => <<"Test connector OK">>,
|
200 => <<"Test connector OK">>,
|
||||||
400 => error_schema('TEST_FAILED', "connector test failed")
|
400 => error_schema('TEST_FAILED', "connector test failed")
|
||||||
|
@ -92,17 +135,19 @@ schema("/connectors") ->
|
||||||
description => <<"List all connectors">>,
|
description => <<"List all connectors">>,
|
||||||
summary => <<"List connectors">>,
|
summary => <<"List connectors">>,
|
||||||
responses => #{
|
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 => #{
|
post => #{
|
||||||
tags => [<<"connectors">>],
|
tags => [<<"connectors">>],
|
||||||
description => <<"Create a new connector by given Id <br>"
|
description => <<"Create a new connector by given Id <br>"
|
||||||
"The ID must be of format 'type:name'">>,
|
"The ID must be of format '{type}:{name}'">>,
|
||||||
summary => <<"Create connector">>,
|
summary => <<"Create connector">>,
|
||||||
requestBody => connector_info(),
|
requestBody => post_request_body_schema(),
|
||||||
responses => #{
|
responses => #{
|
||||||
201 => connector_info(),
|
201 => get_response_body_schema(),
|
||||||
400 => error_schema('ALREADY_EXISTS', "connector already exists")
|
400 => error_schema('ALREADY_EXISTS', "connector already exists")
|
||||||
}
|
}
|
||||||
}
|
}
|
||||||
|
@ -117,7 +162,7 @@ schema("/connectors/:id") ->
|
||||||
summary => <<"Get connector">>,
|
summary => <<"Get connector">>,
|
||||||
parameters => param_path_id(),
|
parameters => param_path_id(),
|
||||||
responses => #{
|
responses => #{
|
||||||
200 => connector_info(),
|
200 => get_response_body_schema(),
|
||||||
404 => error_schema('NOT_FOUND', "Connector not found")
|
404 => error_schema('NOT_FOUND', "Connector not found")
|
||||||
}
|
}
|
||||||
},
|
},
|
||||||
|
@ -126,9 +171,9 @@ schema("/connectors/:id") ->
|
||||||
description => <<"Update an existing connector by Id">>,
|
description => <<"Update an existing connector by Id">>,
|
||||||
summary => <<"Update connector">>,
|
summary => <<"Update connector">>,
|
||||||
parameters => param_path_id(),
|
parameters => param_path_id(),
|
||||||
requestBody => connector_req(),
|
requestBody => put_request_body_schema(),
|
||||||
responses => #{
|
responses => #{
|
||||||
200 => <<"Update connector successfully">>,
|
200 => get_response_body_schema(),
|
||||||
400 => error_schema('UPDATE_FAIL', "Update failed"),
|
400 => error_schema('UPDATE_FAIL', "Update failed"),
|
||||||
404 => error_schema('NOT_FOUND', "Connector not found")
|
404 => error_schema('NOT_FOUND', "Connector not found")
|
||||||
}},
|
}},
|
||||||
|
@ -143,8 +188,8 @@ schema("/connectors/:id") ->
|
||||||
}}
|
}}
|
||||||
}.
|
}.
|
||||||
|
|
||||||
'/connectors_test'(post, #{body := #{<<"bridge_type">> := ConnType} = Params}) ->
|
'/connectors_test'(post, #{body := #{<<"type">> := ConnType} = Params}) ->
|
||||||
case emqx_connector:create_dry_run(ConnType, maps:remove(<<"bridge_type">>, Params)) of
|
case emqx_connector:create_dry_run(ConnType, maps:remove(<<"type">>, Params)) of
|
||||||
ok -> {200};
|
ok -> {200};
|
||||||
{error, Error} ->
|
{error, Error} ->
|
||||||
{400, error_msg('BAD_ARG', Error)}
|
{400, error_msg('BAD_ARG', Error)}
|
||||||
|
|
|
@ -100,7 +100,7 @@ on_start(InstId, Conf) ->
|
||||||
BasicConf = basic_config(Conf),
|
BasicConf = basic_config(Conf),
|
||||||
BridgeConf = BasicConf#{
|
BridgeConf = BasicConf#{
|
||||||
name => InstanceId,
|
name => InstanceId,
|
||||||
clientid => clientid(InstanceId),
|
clientid => clientid(maps:get(clientid, Conf, InstanceId)),
|
||||||
subscriptions => make_sub_confs(maps:get(ingress, Conf, undefined)),
|
subscriptions => make_sub_confs(maps:get(ingress, Conf, undefined)),
|
||||||
forwards => make_forward_confs(maps:get(egress, Conf, undefined))
|
forwards => make_forward_confs(maps:get(egress, Conf, undefined))
|
||||||
},
|
},
|
||||||
|
@ -190,4 +190,4 @@ basic_config(#{
|
||||||
}.
|
}.
|
||||||
|
|
||||||
clientid(Id) ->
|
clientid(Id) ->
|
||||||
list_to_binary(lists:concat([Id, ":", node()])).
|
unicode:characters_to_binary([Id, ":", atom_to_list(node())], utf8).
|
||||||
|
|
|
@ -22,14 +22,13 @@ fields("connectors") ->
|
||||||
];
|
];
|
||||||
|
|
||||||
fields("mqtt_connector") ->
|
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") ->
|
fields("mqtt_connector_info") ->
|
||||||
[{id, sc(binary(), #{desc => "The connector Id"})}]
|
[{id, sc(binary(), #{desc => "The connector Id", example => "mqtt:foo"})}]
|
||||||
++ fields("mqtt_connector");
|
|
||||||
|
|
||||||
fields("mqtt_connector_test_info") ->
|
|
||||||
[{bridge_type, sc(mqtt, #{desc => "The Bridge Type"})}]
|
|
||||||
++ fields("mqtt_connector").
|
++ fields("mqtt_connector").
|
||||||
|
|
||||||
sc(Type, Meta) -> hoconsc:mk(Type, Meta).
|
sc(Type, Meta) -> hoconsc:mk(Type, Meta).
|
||||||
|
|
|
@ -66,8 +66,7 @@ fields("connector") ->
|
||||||
})}
|
})}
|
||||||
, {clientid,
|
, {clientid,
|
||||||
sc(binary(),
|
sc(binary(),
|
||||||
#{ default => "emqx_${nodename}"
|
#{ desc => "The clientid of the MQTT protocol"
|
||||||
, desc => "The clientid of the MQTT protocol"
|
|
||||||
})}
|
})}
|
||||||
, {clean_start,
|
, {clean_start,
|
||||||
sc(boolean(),
|
sc(boolean(),
|
||||||
|
|
|
@ -92,7 +92,7 @@ api_rules_crud() ->
|
||||||
<<"200">> =>
|
<<"200">> =>
|
||||||
emqx_mgmt_util:schema(resp_schema(), <<"Get rule successfully">>)}},
|
emqx_mgmt_util:schema(resp_schema(), <<"Get rule successfully">>)}},
|
||||||
put => #{
|
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()],
|
parameters => [param_path_id()],
|
||||||
'requestBody' => emqx_mgmt_util:schema(put_req_schema(), <<"Rule parameters">>),
|
'requestBody' => emqx_mgmt_util:schema(put_req_schema(), <<"Rule parameters">>),
|
||||||
responses => #{
|
responses => #{
|
||||||
|
@ -100,7 +100,7 @@ api_rules_crud() ->
|
||||||
emqx_mgmt_util:error_schema(<<"Invalid Parameters">>, ['BAD_ARGS']),
|
emqx_mgmt_util:error_schema(<<"Invalid Parameters">>, ['BAD_ARGS']),
|
||||||
<<"200">> =>
|
<<"200">> =>
|
||||||
emqx_mgmt_util:schema(resp_schema(),
|
emqx_mgmt_util:schema(resp_schema(),
|
||||||
<<"Create or update rule successfully">>)}},
|
<<"Update rule successfully">>)}},
|
||||||
delete => #{
|
delete => #{
|
||||||
description => <<"Delete a rule by given Id from all nodes in the cluster">>,
|
description => <<"Delete a rule by given Id from all nodes in the cluster">>,
|
||||||
parameters => [param_path_id()],
|
parameters => [param_path_id()],
|
||||||
|
|
Loading…
Reference in New Issue