yuanbiao
/
emqx
1
0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

chore(gw): update HTTP API docs for gateway

This commit is contained in:
JianBo He 2022-09-30 16:01:23 +08:00
parent 09500f1f45
commit 5fa1e63392
9 changed files with 173 additions and 66 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

39
apps/emqx_gateway/i18n/emqx_gateway_api_authn_i18n.conf
View File

@ -2,70 +2,76 @@ emqx_gateway_api_authn {
get_authn { get_authn {
desc { desc {
en: """Get the gateway authentication""" en: """Gets the configuration of the specified gateway authenticator.</br>
zh: """获取指定网关认证器""" Returns 404 when gateway or authentication is not enabled."""
zh: """获取指定网关认证器的配置
当网关或认证未启用时，返回 404。"""
} }
} }
update_authn { update_authn {
desc { desc {
en: """Update authentication for the gateway""" en: """Update the configuration of the specified gateway authenticator, or disable the authenticator."""
zh: """更新网关认证器""" zh: """更新指定网关认证器的配置，或停用认证器。"""
} }
} }
add_authn { add_authn {
desc { desc {
en: """Add authentication for the gateway""" en: """Enables the authenticator for client authentication for the specified gateway. <\br>
zh: """为指定网关新增认证器""" When the authenticator is not configured or turned off, all client connections are assumed to be allowed. <\br>
Note: Adding only one authenticator is supported in the gateway, rather than allowing multiple authenticators to be configured to form an authentication chain as in MQTT."""
zh: """为指定网关开启认证器实现客户端认证的功能。<\br>
当未配置认证器或关闭认证器时，则认为允许所有客户端的连接。<\br>
注：在网关中仅支持添加一个认证器，而不是像 MQTT 一样允许配置多个认证器构成认证链。"""
} }
} }
delete_authn { delete_authn {
desc { desc {
en: """Remove the gateway authentication""" en: """Delete the authenticator of the specified gateway."""
zh: """删除指定网关的认证器""" zh: """删除指定网关的认证器。"""
} }
} }
list_users { list_users {
desc { desc {
en: """Get the users for the authentication""" en: """Get the users for the authenticator (only supports built_in_database)."""
zh: """获取用户列表（仅支持 built_in_database 类型的认证器）""" zh: """获取用户列表（仅支持 built_in_database 类型的认证器）"""
} }
} }
add_user { add_user {
desc { desc {
en: """Add user for the authentication""" en: """Add user for the authenticator (only supports built_in_database)."""
zh: """添加用户（仅支持 built_in_database 类型的认证器）""" zh: """添加用户（仅支持 built_in_database 类型的认证器）"""
} }
} }
get_user { get_user {
desc { desc {
en: """Get user info from the gateway authentication""" en: """Get user info from the gateway authenticator (only supports built_in_database)"""
zh: """获取用户信息（仅支持 built_in_database 类型的认证器）""" zh: """获取用户信息（仅支持 built_in_database 类型的认证器）"""
} }
} }
update_user { update_user {
desc { desc {
en: """Update the user info for the gateway authentication""" en: """Update the user info for the gateway authenticator (only supports built_in_database)"""
zh: """更新用户信息（仅支持 built_in_database 类型的认证器）""" zh: """更新用户信息（仅支持 built_in_database 类型的认证器）"""
} }
} }
delete_user { delete_user {
desc { desc {
en: """Delete the user for the gateway authentication""" en: """Delete the user for the gateway authenticator (only supports built_in_database)"""
zh: """删除用户（仅支持 built_in_database 类型的认证器）""" zh: """删除用户（仅支持 built_in_database 类型的认证器）"""
} }
} }
import_users { import_users {
desc { desc {
en: """Import users into the gateway authentication""" en: """Import users into the gateway authenticator (only supports built_in_database)"""
zh: """导入用户（仅支持 built_in_database 类型的认证器）""" zh: """导入用户（仅支持 built_in_database 类型的认证器）"""
} }
} }
@ -79,8 +85,8 @@ emqx_gateway_api_authn {
like_user_id { like_user_id {
desc { desc {
en: """Fuzzy search by user_id (username or clientid)""" en: """Fuzzy search using user ID (username or clientid), only supports search by substring."""
zh: """用户 ID （username 或 clientid）模糊搜索""" zh: """使用用户 ID （username 或 clientid）模糊搜索，仅支持按子串的方式进行搜索。"""
} }
} }
@ -90,5 +96,4 @@ emqx_gateway_api_authn {
zh: """是否是超级用户""" zh: """是否是超级用户"""
} }
} }
} }

42
apps/emqx_gateway/i18n/emqx_gateway_api_i18n.conf
View File

@ -2,15 +2,17 @@ emqx_gateway_api {
list_gateway { list_gateway {
desc { desc {
en: """Get gateway list""" en: """This API returns an overview info for the specified or all gateways.
zh: """获取网关列表""" including current running status, number of connections, listener status, etc."""
zh: """该接口会返回指定或所有网关的概览状态，
包括当前状态、连接数、监听器状态等。"""
} }
} }
enable_gateway { enable_gateway {
desc { desc {
en: """Enable a gateway""" en: """Enable a gateway by confs."""
zh: """启用某网关""" zh: """使用配置启动某一网关。"""
} }
} }
@ -23,15 +25,17 @@ emqx_gateway_api {
delete_gateway { delete_gateway {
desc { desc {
en: """Delete/Unload the gateway""" en: """Unload the specified gateway"""
zh: """删除/禁用某网关""" zh: """停用指定网关"""
} }
} }
update_gateway { update_gateway {
desc { desc {
en: """Update the gateway configurations/status""" en: """Update the gateway basic configurations and running status.</br>
zh: """更新网关配置或启用状态""" Note: The Authentication and Listener configurations should be updated by other special APIs. """
zh: """更新指定网关的基础配置、和启用的状态。</br>
注：认证、和监听器的配置更新需参考对应的 API 接口。"""
} }
} }
@ -42,13 +46,33 @@ emqx_gateway_api {
} }
} }
gateway_name_in_qs {
desc {
en: """Gateway Name.</br>
It's enum with `stomp`, `mqttsn`, `coap`, `lwm2m`, `exproto`
"""
zh: """网关名称.</br>
可取值为 `stomp`、`mqttsn`、`coap`、`lwm2m`、`exproto`
"""
}
}
gateway_status { gateway_status {
desc { desc {
en: """Gateway Status""" en: """Gateway status"""
zh: """网关启用状态""" zh: """网关启用状态"""
} }
} }
gateway_status_in_qs {
desc {
en: """Filter gateways by status.</br>
It is enum with `running`, `stopped`, `unloaded`"""
zh: """通过网关状态筛选</br>
可选值为 `running`、`stopped`、`unloaded`"""
}
}
gateway_created_at { gateway_created_at {
desc { desc {
en: """The Gateway created datetime""" en: """The Gateway created datetime"""

53
apps/emqx_gateway/i18n/emqx_gateway_api_listeners_i18n.conf
View File

@ -2,105 +2,109 @@ emqx_gateway_api_listeners {
list_listeners { list_listeners {
desc { desc {
en: """Get the gateway listeners""" en: """Gets a list of gateway listeners. This interface returns all the configs of the listener (including the authenticator on that listener), as well as the status of that listener running in the cluster."""
zh: """获取网关监听器列表""" zh: """获取网关监听器列表。该接口会返回监听器所有的配置（包括该监听器上的认证器），同时也会返回该监听器在集群中运行的状态。"""
} }
} }
add_listener { add_listener {
desc { desc {
en: """Create the gateway listener""" en: """Create the gateway listener.</br>
zh: """为指定网关添加监听器""" Note: For listener types not supported by a gateway, this API returns `400: BAD_REQUEST`."""
zh: """为指定网关添加监听器。</br>
注：对于某网关不支持的监听器类型，该接口会返回 `400: BAD_REQUEST`。"""
} }
} }
get_listener { get_listener {
desc { desc {
en: """Get the gateway listener configurations""" en: """Get the gateway listener configs"""
zh: """获取指定监听器信息""" zh: """获取指定网关监听器的配置。"""
} }
} }
delete_listener { delete_listener {
desc { desc {
en: """Delete the gateway listener""" en: """Delete the gateway listener. All connected clients under the deleted listener will be disconnected."""
zh: """删除监听器""" zh: """删除指定监听器。被删除的监听器下所有已连接的客户端都会离线。"""
} }
} }
update_listener { update_listener {
desc { desc {
en: """Update the gateway listener""" en: """Update the gateway listener. The listener being updated performs a restart and all clients connected to that listener will be disconnected."""
zh: """更新监听器""" zh: """更新某网关监听器的配置。被更新的监听器会执行重启，所有已连接到该监听器上的客户端都会被断开。"""
} }
} }
get_listener_authn { get_listener_authn {
desc { desc {
en: """Get the listener's authentication info""" en: """Get the listener's authenticator configs."""
zh: """获取监听器的认证器信息""" zh: """获取监听器的认证器配置。"""
} }
} }
add_listener_authn { add_listener_authn {
desc { desc {
en: """Add authentication for the listener""" en: """Enable authenticator for specified listener for client authentication.</br>
zh: """为指定监听器添加认证器""" When authenticator is enabled for a listener, all clients connected to that listener will use that authenticator for authentication."""
zh: """为指定监听器开启认证器以实现客户端认证的能力。</br>
当某一监听器开启认证后，所有连接到该监听器的客户端会使用该认证器进行认证。"""
} }
} }
update_listener_authn { update_listener_authn {
desc { desc {
en: """Update authentication for the listener""" en: """Update authenticator configs for the listener, or disable/enable it."""
zh: """更新指定监听上的认证器配置""" zh: """更新指定监听器的认证器配置，或停用/启用该认证器。"""
} }
} }
delete_listener_authn { delete_listener_authn {
desc { desc {
en: """Remove authentication for the listener""" en: """Remove authenticator for the listener."""
zh: """为指定监听器移除认证器""" zh: """移除指定监听器的认证器。"""
} }
} }
list_users { list_users {
desc { desc {
en: """Get the users for the authentication""" en: """Get the users for the authenticator (only supports built_in_database)"""
zh: """获取用户列表（仅支持 built_in_database 类型的认证器）""" zh: """获取用户列表（仅支持 built_in_database 类型的认证器）"""
} }
} }
add_user { add_user {
desc { desc {
en: """Add user for the authentication""" en: """Add user for the authenticator (only supports built_in_database)"""
zh: """添加用户（仅支持 built_in_database 类型的认证器）""" zh: """添加用户（仅支持 built_in_database 类型的认证器）"""
} }
} }
get_user { get_user {
desc { desc {
en: """Get user info from the gateway authentication""" en: """Get user info from the gateway authenticator (only supports built_in_database)"""
zh: """获取用户信息（仅支持 built_in_database 类型的认证器）""" zh: """获取用户信息（仅支持 built_in_database 类型的认证器）"""
} }
} }
update_user { update_user {
desc { desc {
en: """Update the user info for the gateway authentication""" en: """Update the user info for the gateway authenticator (only supports built_in_database)"""
zh: """更新用户信息（仅支持 built_in_database 类型的认证器）""" zh: """更新用户信息（仅支持 built_in_database 类型的认证器）"""
} }
} }
delete_user { delete_user {
desc { desc {
en: """Delete the user for the gateway authentication""" en: """Delete the user for the gateway authenticator (only supports built_in_database)"""
zh: """删除用户（仅支持 built_in_database 类型的认证器）""" zh: """删除用户（仅支持 built_in_database 类型的认证器）"""
} }
} }
import_users { import_users {
desc { desc {
en: """Import users into the gateway authentication""" en: """Import users into the gateway authenticator (only supports built_in_database)"""
zh: """导入用户（仅支持 built_in_database 类型的认证器）""" zh: """导入用户（仅支持 built_in_database 类型的认证器）"""
} }
} }
@ -139,5 +143,4 @@ emqx_gateway_api_listeners {
zh: """当前连接数""" zh: """当前连接数"""
} }
} }
} }

3
apps/emqx_gateway/src/coap/emqx_coap_api.erl
View File

@ -48,8 +48,9 @@ schema(?PREFIX ++ "/request") ->
#{ #{
operationId => request, operationId => request,
post => #{ post => #{
tags => [<<"CoAP">>], tags => [<<"Gateways">>],
desc => ?DESC(send_coap_request), desc => ?DESC(send_coap_request),
summary => <<"Send a Request to a Client">>,
parameters => request_parameters(), parameters => request_parameters(),
requestBody => request_body(), requestBody => request_body(),
responses => #{ responses => #{

16
apps/emqx_gateway/src/emqx_gateway_api.erl
View File

@ -164,7 +164,9 @@ schema("/gateways") ->
'operationId' => gateway, 'operationId' => gateway,
get => get =>
#{ #{
tags => [<<"Gateways">>],
desc => ?DESC(list_gateway), desc => ?DESC(list_gateway),
summary => <<"List All Gateways">>,
parameters => params_gateway_status_in_qs(), parameters => params_gateway_status_in_qs(),
responses => responses =>
?STANDARD_RESP( ?STANDARD_RESP(
@ -178,7 +180,9 @@ schema("/gateways") ->
}, },
post => post =>
#{ #{
tags => [<<"Gateways">>],
desc => ?DESC(enable_gateway), desc => ?DESC(enable_gateway),
summary => <<"Enable a Gateway">>,
%% TODO: distinguish create & response swagger schema %% TODO: distinguish create & response swagger schema
'requestBody' => schema_gateways_conf(), 'requestBody' => schema_gateways_conf(),
responses => responses =>
@ -190,21 +194,27 @@ schema("/gateways/:name") ->
'operationId' => gateway_insta, 'operationId' => gateway_insta,
get => get =>
#{ #{
tags => [<<"Gateways">>],
desc => ?DESC(get_gateway), desc => ?DESC(get_gateway),
summary => <<"Get the Gateway">>,
parameters => params_gateway_name_in_path(), parameters => params_gateway_name_in_path(),
responses => responses =>
?STANDARD_RESP(#{200 => schema_gateways_conf()}) ?STANDARD_RESP(#{200 => schema_gateways_conf()})
}, },
delete => delete =>
#{ #{
tags => [<<"Gateways">>],
desc => ?DESC(delete_gateway), desc => ?DESC(delete_gateway),
summary => <<"Unload the gateway">>,
parameters => params_gateway_name_in_path(), parameters => params_gateway_name_in_path(),
responses => responses =>
?STANDARD_RESP(#{204 => <<"Deleted">>}) ?STANDARD_RESP(#{204 => <<"Deleted">>})
}, },
put => put =>
#{ #{
tags => [<<"Gateways">>],
desc => ?DESC(update_gateway), desc => ?DESC(update_gateway),
summary => <<"Update the gateway confs">>,
parameters => params_gateway_name_in_path(), parameters => params_gateway_name_in_path(),
'requestBody' => schema_update_gateways_conf(), 'requestBody' => schema_update_gateways_conf(),
responses => responses =>
@ -224,8 +234,8 @@ params_gateway_name_in_path() ->
binary(), binary(),
#{ #{
in => path, in => path,
desc => ?DESC(gateway_name), desc => ?DESC(gateway_name_in_qs),
example => <<"">> example => <<"stomp">>
} }
)} )}
]. ].
@ -239,7 +249,7 @@ params_gateway_status_in_qs() ->
#{ #{
in => query, in => query,
required => false, required => false,
desc => ?DESC(gateway_status), desc => ?DESC(gateway_status_in_qs),
example => <<"">> example => <<"">>
} }
)} )}

29
apps/emqx_gateway/src/emqx_gateway_api_authn.erl
View File

@ -75,6 +75,7 @@ authn(get, #{bindings := #{name := Name0}}) ->
Authn -> {200, Authn} Authn -> {200, Authn}
catch catch
error:{config_not_found, _} -> error:{config_not_found, _} ->
%% FIXME: should return 404?
{204} {204}
end end
end); end);
@ -181,19 +182,23 @@ schema("/gateways/:name/authentication") ->
'operationId' => authn, 'operationId' => authn,
get => get =>
#{ #{
tag => [<<"Gateways">>],
desc => ?DESC(get_authn), desc => ?DESC(get_authn),
summary => <<"Get Authenticator Configuration">>,
parameters => params_gateway_name_in_path(), parameters => params_gateway_name_in_path(),
responses => responses =>
?STANDARD_RESP( ?STANDARD_RESP(
#{ #{
200 => schema_authn(), 200 => schema_authn(),
204 => <<"Authentication does not initiated">> 204 => <<"Authenticator doesn't initiated">>
} }
) )
}, },
put => put =>
#{ #{
tag => [<<"Gateways">>],
desc => ?DESC(update_authn), desc => ?DESC(update_authn),
summary => <<"Update Authenticator Configuration">>,
parameters => params_gateway_name_in_path(), parameters => params_gateway_name_in_path(),
'requestBody' => schema_authn(), 'requestBody' => schema_authn(),
responses => responses =>
@ -201,7 +206,9 @@ schema("/gateways/:name/authentication") ->
}, },
post => post =>
#{ #{
tag => [<<"Gateways">>],
desc => ?DESC(add_authn), desc => ?DESC(add_authn),
summary => <<"Create an Authenticator for a Gateway">>,
parameters => params_gateway_name_in_path(), parameters => params_gateway_name_in_path(),
'requestBody' => schema_authn(), 'requestBody' => schema_authn(),
responses => responses =>
@ -209,7 +216,9 @@ schema("/gateways/:name/authentication") ->
}, },
delete => delete =>
#{ #{
tag => [<<"Gateways">>],
desc => ?DESC(delete_authn), desc => ?DESC(delete_authn),
summary => <<"Delete the Gateway Authenticator">>,
parameters => params_gateway_name_in_path(), parameters => params_gateway_name_in_path(),
responses => responses =>
?STANDARD_RESP(#{204 => <<"Deleted">>}) ?STANDARD_RESP(#{204 => <<"Deleted">>})
@ -220,7 +229,9 @@ schema("/gateways/:name/authentication/users") ->
'operationId' => users, 'operationId' => users,
get => get =>
#{ #{
tag => [<<"Gateways">>],
desc => ?DESC(list_users), desc => ?DESC(list_users),
summary => <<"List users for a Gateway Authenticator">>,
parameters => params_gateway_name_in_path() ++ parameters => params_gateway_name_in_path() ++
params_paging_in_qs() ++ params_paging_in_qs() ++
params_fuzzy_in_qs(), params_fuzzy_in_qs(),
@ -236,7 +247,9 @@ schema("/gateways/:name/authentication/users") ->
}, },
post => post =>
#{ #{
tag => [<<"Gateways">>],
desc => ?DESC(add_user), desc => ?DESC(add_user),
summary => <<"Add User for a Gateway Authenticator">>,
parameters => params_gateway_name_in_path(), parameters => params_gateway_name_in_path(),
'requestBody' => emqx_dashboard_swagger:schema_with_examples( 'requestBody' => emqx_dashboard_swagger:schema_with_examples(
ref(emqx_authn_api, request_user_create), ref(emqx_authn_api, request_user_create),
@ -258,7 +271,9 @@ schema("/gateways/:name/authentication/users/:uid") ->
'operationId' => users_insta, 'operationId' => users_insta,
get => get =>
#{ #{
tag => [<<"Gateways">>],
desc => ?DESC(get_user), desc => ?DESC(get_user),
summary => <<"Get User Info for a Gateway Authenticator">>,
parameters => params_gateway_name_in_path() ++ parameters => params_gateway_name_in_path() ++
params_userid_in_path(), params_userid_in_path(),
responses => responses =>
@ -273,7 +288,9 @@ schema("/gateways/:name/authentication/users/:uid") ->
}, },
put => put =>
#{ #{
tag => [<<"Gateways">>],
desc => ?DESC(update_user), desc => ?DESC(update_user),
summary => <<"Update User Info for a Gateway Authenticator">>,
parameters => params_gateway_name_in_path() ++ parameters => params_gateway_name_in_path() ++
params_userid_in_path(), params_userid_in_path(),
'requestBody' => emqx_dashboard_swagger:schema_with_examples( 'requestBody' => emqx_dashboard_swagger:schema_with_examples(
@ -292,7 +309,9 @@ schema("/gateways/:name/authentication/users/:uid") ->
}, },
delete => delete =>
#{ #{
tag => [<<"Gateways">>],
desc => ?DESC(delete_user), desc => ?DESC(delete_user),
summary => <<"Delete User for a Gateway Authenticator">>,
parameters => params_gateway_name_in_path() ++ parameters => params_gateway_name_in_path() ++
params_userid_in_path(), params_userid_in_path(),
responses => responses =>
@ -311,8 +330,8 @@ params_gateway_name_in_path() ->
binary(), binary(),
#{ #{
in => path, in => path,
desc => ?DESC(emqx_gateway_api, gateway_name), desc => ?DESC(emqx_gateway_api, gateway_name_in_qs),
example => <<"">> example => <<"stomp">>
} }
)} )}
]. ].
@ -325,7 +344,7 @@ params_userid_in_path() ->
#{ #{
in => path, in => path,
desc => ?DESC(user_id), desc => ?DESC(user_id),
example => <<"">> example => <<"test_username">>
} }
)} )}
]. ].
@ -343,7 +362,7 @@ params_fuzzy_in_qs() ->
in => query, in => query,
required => false, required => false,
desc => ?DESC(like_user_id), desc => ?DESC(like_user_id),
example => <<"username">> example => <<"test_">>
} }
)}, )},
{is_superuser, {is_superuser,

12
apps/emqx_gateway/src/emqx_gateway_api_clients.erl
View File

@ -467,7 +467,9 @@ schema("/gateways/:name/clients") ->
'operationId' => clients, 'operationId' => clients,
get => get =>
#{ #{
tag => [<<"Gateways">>],
desc => ?DESC(list_clients), desc => ?DESC(list_clients),
summary => <<"List Gateway's Clients">>,
parameters => params_client_query(), parameters => params_client_query(),
responses => responses =>
?STANDARD_RESP(#{200 => schema_client_list()}) ?STANDARD_RESP(#{200 => schema_client_list()})
@ -478,14 +480,18 @@ schema("/gateways/:name/clients/:clientid") ->
'operationId' => clients_insta, 'operationId' => clients_insta,
get => get =>
#{ #{
tag => [<<"Gateways">>],
desc => ?DESC(get_client), desc => ?DESC(get_client),
summary => <<"Get Client Info">>,
parameters => params_client_insta(), parameters => params_client_insta(),
responses => responses =>
?STANDARD_RESP(#{200 => schema_client()}) ?STANDARD_RESP(#{200 => schema_client()})
}, },
delete => delete =>
#{ #{
tag => [<<"Gateways">>],
desc => ?DESC(kick_client), desc => ?DESC(kick_client),
summary => <<"Kick out Client">>,
parameters => params_client_insta(), parameters => params_client_insta(),
responses => responses =>
?STANDARD_RESP(#{204 => <<"Kicked">>}) ?STANDARD_RESP(#{204 => <<"Kicked">>})
@ -496,7 +502,9 @@ schema("/gateways/:name/clients/:clientid/subscriptions") ->
'operationId' => subscriptions, 'operationId' => subscriptions,
get => get =>
#{ #{
tag => [<<"Gateways">>],
desc => ?DESC(list_subscriptions), desc => ?DESC(list_subscriptions),
summary => <<"List Client's Subscription">>,
parameters => params_client_insta(), parameters => params_client_insta(),
responses => responses =>
?STANDARD_RESP( ?STANDARD_RESP(
@ -510,7 +518,9 @@ schema("/gateways/:name/clients/:clientid/subscriptions") ->
}, },
post => post =>
#{ #{
tag => [<<"Gateways">>],
desc => ?DESC(add_subscription), desc => ?DESC(add_subscription),
summary => <<"Add Subscription for Client">>,
parameters => params_client_insta(), parameters => params_client_insta(),
'requestBody' => emqx_dashboard_swagger:schema_with_examples( 'requestBody' => emqx_dashboard_swagger:schema_with_examples(
ref(subscription), ref(subscription),
@ -532,7 +542,9 @@ schema("/gateways/:name/clients/:clientid/subscriptions/:topic") ->
'operationId' => subscriptions, 'operationId' => subscriptions,
delete => delete =>
#{ #{
tag => [<<"Gateways">>],
desc => ?DESC(delete_subscription), desc => ?DESC(delete_subscription),
summary => <<"Delete Client's Subscription">>,
parameters => params_topic_name_in_path() ++ params_client_insta(), parameters => params_topic_name_in_path() ++ params_client_insta(),
responses => responses =>
?STANDARD_RESP(#{204 => <<"Unsubscribed">>}) ?STANDARD_RESP(#{204 => <<"Unsubscribed">>})

33
apps/emqx_gateway/src/emqx_gateway_api_listeners.erl
View File

@ -358,7 +358,9 @@ schema("/gateways/:name/listeners") ->
'operationId' => listeners, 'operationId' => listeners,
get => get =>
#{ #{
tags => [<<"Gateways">>],
desc => ?DESC(list_listeners), desc => ?DESC(list_listeners),
summary => <<"List All Listener">>,
parameters => params_gateway_name_in_path(), parameters => params_gateway_name_in_path(),
responses => responses =>
?STANDARD_RESP( ?STANDARD_RESP(
@ -372,7 +374,9 @@ schema("/gateways/:name/listeners") ->
}, },
post => post =>
#{ #{
tags => [<<"Gateways">>],
desc => ?DESC(add_listener), desc => ?DESC(add_listener),
summary => <<"Add a Listener">>,
parameters => params_gateway_name_in_path(), parameters => params_gateway_name_in_path(),
%% XXX: How to distinguish the different listener supported by %% XXX: How to distinguish the different listener supported by
%% different types of gateways? %% different types of gateways?
@ -396,7 +400,9 @@ schema("/gateways/:name/listeners/:id") ->
'operationId' => listeners_insta, 'operationId' => listeners_insta,
get => get =>
#{ #{
tags => [<<"Gateways">>],
desc => ?DESC(get_listener), desc => ?DESC(get_listener),
summary => <<"Get the Listener Configs">>,
parameters => params_gateway_name_in_path() ++ parameters => params_gateway_name_in_path() ++
params_listener_id_in_path(), params_listener_id_in_path(),
responses => responses =>
@ -411,7 +417,9 @@ schema("/gateways/:name/listeners/:id") ->
}, },
delete => delete =>
#{ #{
tags => [<<"Gateways">>],
desc => ?DESC(delete_listener), desc => ?DESC(delete_listener),
summary => <<"Delete the Listener">>,
parameters => params_gateway_name_in_path() ++ parameters => params_gateway_name_in_path() ++
params_listener_id_in_path(), params_listener_id_in_path(),
responses => responses =>
@ -419,7 +427,9 @@ schema("/gateways/:name/listeners/:id") ->
}, },
put => put =>
#{ #{
tags => [<<"Gateways">>],
desc => ?DESC(update_listener), desc => ?DESC(update_listener),
summary => <<"Update the Listener Configs">>,
parameters => params_gateway_name_in_path() ++ parameters => params_gateway_name_in_path() ++
params_listener_id_in_path(), params_listener_id_in_path(),
'requestBody' => emqx_dashboard_swagger:schema_with_examples( 'requestBody' => emqx_dashboard_swagger:schema_with_examples(
@ -442,7 +452,9 @@ schema("/gateways/:name/listeners/:id/authentication") ->
'operationId' => listeners_insta_authn, 'operationId' => listeners_insta_authn,
get => get =>
#{ #{
tags => [<<"Gateways">>],
desc => ?DESC(get_listener_authn), desc => ?DESC(get_listener_authn),
summary => <<"Get the Listener's Authenticator">>,
parameters => params_gateway_name_in_path() ++ parameters => params_gateway_name_in_path() ++
params_listener_id_in_path(), params_listener_id_in_path(),
responses => responses =>
@ -455,7 +467,9 @@ schema("/gateways/:name/listeners/:id/authentication") ->
}, },
post => post =>
#{ #{
tags => [<<"Gateways">>],
desc => ?DESC(add_listener_authn), desc => ?DESC(add_listener_authn),
summary => <<"Create an Authenticator for a Listener">>,
parameters => params_gateway_name_in_path() ++ parameters => params_gateway_name_in_path() ++
params_listener_id_in_path(), params_listener_id_in_path(),
'requestBody' => schema_authn(), 'requestBody' => schema_authn(),
@ -464,7 +478,9 @@ schema("/gateways/:name/listeners/:id/authentication") ->
}, },
put => put =>
#{ #{
tags => [<<"Gateways">>],
desc => ?DESC(update_listener_authn), desc => ?DESC(update_listener_authn),
summary => <<"Update the Listener Authenticator configs">>,
parameters => params_gateway_name_in_path() ++ parameters => params_gateway_name_in_path() ++
params_listener_id_in_path(), params_listener_id_in_path(),
'requestBody' => schema_authn(), 'requestBody' => schema_authn(),
@ -473,7 +489,9 @@ schema("/gateways/:name/listeners/:id/authentication") ->
}, },
delete => delete =>
#{ #{
tags => [<<"Gateways">>],
desc => ?DESC(delete_listener_authn), desc => ?DESC(delete_listener_authn),
summary => <<"Delete the Listener's Authenticator">>,
parameters => params_gateway_name_in_path() ++ parameters => params_gateway_name_in_path() ++
params_listener_id_in_path(), params_listener_id_in_path(),
responses => responses =>
@ -485,7 +503,9 @@ schema("/gateways/:name/listeners/:id/authentication/users") ->
'operationId' => users, 'operationId' => users,
get => get =>
#{ #{
tags => [<<"Gateways">>],
desc => ?DESC(list_users), desc => ?DESC(list_users),
summary => <<"List Authenticator's Users">>,
parameters => params_gateway_name_in_path() ++ parameters => params_gateway_name_in_path() ++
params_listener_id_in_path() ++ params_listener_id_in_path() ++
params_paging_in_qs(), params_paging_in_qs(),
@ -501,7 +521,9 @@ schema("/gateways/:name/listeners/:id/authentication/users") ->
}, },
post => post =>
#{ #{
tags => [<<"Gateways">>],
desc => ?DESC(add_user), desc => ?DESC(add_user),
summary => <<"Add User for an Authenticator">>,
parameters => params_gateway_name_in_path() ++ parameters => params_gateway_name_in_path() ++
params_listener_id_in_path(), params_listener_id_in_path(),
'requestBody' => emqx_dashboard_swagger:schema_with_examples( 'requestBody' => emqx_dashboard_swagger:schema_with_examples(
@ -524,7 +546,9 @@ schema("/gateways/:name/listeners/:id/authentication/users/:uid") ->
'operationId' => users_insta, 'operationId' => users_insta,
get => get =>
#{ #{
tags => [<<"Gateways">>],
desc => ?DESC(get_user), desc => ?DESC(get_user),
summary => <<"Get User Info">>,
parameters => params_gateway_name_in_path() ++ parameters => params_gateway_name_in_path() ++
params_listener_id_in_path() ++ params_listener_id_in_path() ++
params_userid_in_path(), params_userid_in_path(),
@ -540,7 +564,9 @@ schema("/gateways/:name/listeners/:id/authentication/users/:uid") ->
}, },
put => put =>
#{ #{
tags => [<<"Gateways">>],
desc => ?DESC(update_user), desc => ?DESC(update_user),
summary => <<"Update User Info">>,
parameters => params_gateway_name_in_path() ++ parameters => params_gateway_name_in_path() ++
params_listener_id_in_path() ++ params_listener_id_in_path() ++
params_userid_in_path(), params_userid_in_path(),
@ -560,7 +586,9 @@ schema("/gateways/:name/listeners/:id/authentication/users/:uid") ->
}, },
delete => delete =>
#{ #{
tags => [<<"Gateways">>],
desc => ?DESC(delete_user), desc => ?DESC(delete_user),
summary => <<"Delete User">>,
parameters => params_gateway_name_in_path() ++ parameters => params_gateway_name_in_path() ++
params_listener_id_in_path() ++ params_listener_id_in_path() ++
params_userid_in_path(), params_userid_in_path(),
@ -570,6 +598,7 @@ schema("/gateways/:name/listeners/:id/authentication/users/:uid") ->
}; };
schema(Path) -> schema(Path) ->
emqx_gateway_utils:make_compatible_schema(Path, fun schema/1). emqx_gateway_utils:make_compatible_schema(Path, fun schema/1).
%%-------------------------------------------------------------------- %%--------------------------------------------------------------------
%% params defines %% params defines
@ -580,8 +609,8 @@ params_gateway_name_in_path() ->
binary(), binary(),
#{ #{
in => path, in => path,
desc => ?DESC(emqx_gateway_api, gateway_name), desc => ?DESC(emqx_gateway_api, gateway_name_in_qs),
example => <<"">> example => <<"stomp">>
} }
)} )}
]. ].

12
apps/emqx_gateway/src/lwm2m/emqx_lwm2m_api.erl
View File

@ -45,8 +45,9 @@ schema(?PATH("/lookup")) ->
#{ #{
'operationId' => lookup, 'operationId' => lookup,
get => #{ get => #{
tags => [<<"LwM2M">>], tags => [<<"Gateways">>],
desc => ?DESC(lookup_resource), desc => ?DESC(lookup_resource),
summary => <<"List Client's Resources">>,
parameters => [ parameters => [
{clientid, mk(binary(), #{in => path, example => "urn:oma:lwm2m:oma:2"})}, {clientid, mk(binary(), #{in => path, example => "urn:oma:lwm2m:oma:2"})},
{path, mk(binary(), #{in => query, required => true, example => "/3/0/7"})}, {path, mk(binary(), #{in => query, required => true, example => "/3/0/7"})},
@ -69,8 +70,9 @@ schema(?PATH("/observe")) ->
#{ #{
'operationId' => observe, 'operationId' => observe,
post => #{ post => #{
tags => [<<"LwM2M">>], tags => [<<"Gateways">>],
desc => ?DESC(observe_resource), desc => ?DESC(observe_resource),
summary => <<"Observe a Resource">>,
parameters => [ parameters => [
{clientid, mk(binary(), #{in => path, example => "urn:oma:lwm2m:oma:2"})}, {clientid, mk(binary(), #{in => path, example => "urn:oma:lwm2m:oma:2"})},
{path, mk(binary(), #{in => query, required => true, example => "/3/0/7"})}, {path, mk(binary(), #{in => query, required => true, example => "/3/0/7"})},
@ -87,8 +89,9 @@ schema(?PATH("/read")) ->
#{ #{
'operationId' => read, 'operationId' => read,
post => #{ post => #{
tags => [<<"LwM2M">>], tags => [<<"Gateways">>],
desc => ?DESC(read_resource), desc => ?DESC(read_resource),
summary => <<"Read Value from a Resource Path">>,
parameters => [ parameters => [
{clientid, mk(binary(), #{in => path, example => "urn:oma:lwm2m:oma:2"})}, {clientid, mk(binary(), #{in => path, example => "urn:oma:lwm2m:oma:2"})},
{path, mk(binary(), #{in => query, required => true, example => "/3/0/7"})} {path, mk(binary(), #{in => query, required => true, example => "/3/0/7"})}
@ -104,7 +107,8 @@ schema(?PATH("/write")) ->
'operationId' => write, 'operationId' => write,
post => #{ post => #{
desc => ?DESC(write_resource), desc => ?DESC(write_resource),
tags => [<<"LwM2M">>], tags => [<<"Gateways">>],
summary => <<"Write a Value to Resource Path">>,
parameters => [ parameters => [
{clientid, mk(binary(), #{in => path, example => "urn:oma:lwm2m:oma:2"})}, {clientid, mk(binary(), #{in => path, example => "urn:oma:lwm2m:oma:2"})},
{path, mk(binary(), #{in => query, required => true, example => "/3/0/7"})}, {path, mk(binary(), #{in => query, required => true, example => "/3/0/7"})},