From 935513d38c6272f7ebd1843c98bf85613835cb0a Mon Sep 17 00:00:00 2001 From: Thales Macedo Garitezi Date: Mon, 31 Oct 2022 14:02:33 -0300 Subject: [PATCH 1/2] docs(fix): remove dynamic example paths from api docs --- apps/emqx_exhook/src/emqx_exhook_api.erl | 6 +++--- apps/emqx_gateway/src/emqx_gateway_api.erl | 4 ++-- .../src/emqx_gateway_api_listeners.erl | 18 +++++++++--------- apps/emqx_gateway/src/emqx_gateway_schema.erl | 7 ++++++- 4 files changed, 20 insertions(+), 15 deletions(-) diff --git a/apps/emqx_exhook/src/emqx_exhook_api.erl b/apps/emqx_exhook/src/emqx_exhook_api.erl index 921a4df68..6676c4503 100644 --- a/apps/emqx_exhook/src/emqx_exhook_api.erl +++ b/apps/emqx_exhook/src/emqx_exhook_api.erl @@ -219,9 +219,9 @@ params_server_name_in_path() -> server_conf_schema() -> SSL = #{ enable => false, - cacertfile => emqx:cert_file(<<"cacert.pem">>), - certfile => emqx:cert_file(<<"cert.pem">>), - keyfile => emqx:cert_file(<<"key.pem">>) + cacertfile => <<"/etc/emqx/certs/cacert.pem">>, + certfile => <<"/etc/emqx/certs/cert.pem">>, + keyfile => <<"/etc/emqx/certs/key.pem">> }, schema_with_example( ref(server_config), diff --git a/apps/emqx_gateway/src/emqx_gateway_api.erl b/apps/emqx_gateway/src/emqx_gateway_api.erl index 87301e34f..5fbca8b7b 100644 --- a/apps/emqx_gateway/src/emqx_gateway_api.erl +++ b/apps/emqx_gateway/src/emqx_gateway_api.erl @@ -686,7 +686,7 @@ examples_gateway_confs() -> enable_stats => true, idle_timeout => <<"30s">>, mountpoint => <<"lwm2m/">>, - xml_dir => emqx:etc_file(<<"lwm2m_xml">>), + xml_dir => <<"/etc/emqx/lwm2m_xml">>, lifetime_min => <<"1s">>, lifetime_max => <<"86400s">>, qmode_time_window => <<"22s">>, @@ -805,7 +805,7 @@ examples_update_gateway_confs() -> enable_stats => true, idle_timeout => <<"30s">>, mountpoint => <<"lwm2m2/">>, - xml_dir => emqx:etc_file(<<"lwm2m_xml">>), + xml_dir => <<"/etc/emqx/lwm2m_xml">>, lifetime_min => <<"1s">>, lifetime_max => <<"86400s">>, qmode_time_window => <<"22s">>, diff --git a/apps/emqx_gateway/src/emqx_gateway_api_listeners.erl b/apps/emqx_gateway/src/emqx_gateway_api_listeners.erl index 4e4e2be38..08bf37a47 100644 --- a/apps/emqx_gateway/src/emqx_gateway_api_listeners.erl +++ b/apps/emqx_gateway/src/emqx_gateway_api_listeners.erl @@ -756,9 +756,9 @@ examples_listener() -> <<"tlsv1.1">>, <<"tlsv1">> ], - cacertfile => emqx:cert_file(<<"cacert.pem">>), - certfile => emqx:cert_file(<<"cert.pem">>), - keyfile => emqx:cert_file(<<"key.pem">>), + cacertfile => <<"/etc/emqx/certs/cacert.pem">>, + certfile => <<"/etc/emqx/certs/cert.pem">>, + keyfile => <<"/etc/emqx/certs/key.pem">>, verify => <<"verify_none">>, fail_if_no_peer_cert => false }, @@ -802,9 +802,9 @@ examples_listener() -> dtls_options => #{ versions => [<<"dtlsv1.2">>, <<"dtlsv1">>], - cacertfile => emqx:cert_file(<<"cacert.pem">>), - certfile => emqx:cert_file(<<"cert.pem">>), - keyfile => emqx:cert_file(<<"key.pem">>), + cacertfile => <<"/etc/emqx/certs/cacert.pem">>, + certfile => <<"/etc/emqx/certs/cert.pem">>, + keyfile => <<"/etc/emqx/certs/key.pem">>, verify => <<"verify_none">>, fail_if_no_peer_cert => false }, @@ -829,9 +829,9 @@ examples_listener() -> dtls_options => #{ versions => [<<"dtlsv1.2">>, <<"dtlsv1">>], - cacertfile => emqx:cert_file(<<"cacert.pem">>), - certfile => emqx:cert_file(<<"cert.pem">>), - keyfile => emqx:cert_file(<<"key.pem">>), + cacertfile => <<"/etc/emqx/certs/cacert.pem">>, + certfile => <<"/etc/emqx/certs/cert.pem">>, + keyfile => <<"/etc/emqx/certs/key.pem">>, verify => <<"verify_none">>, user_lookup_fun => <<"emqx_tls_psk:lookup">>, ciphers => diff --git a/apps/emqx_gateway/src/emqx_gateway_schema.erl b/apps/emqx_gateway/src/emqx_gateway_schema.erl index e5d6dd52a..c58d2f74c 100644 --- a/apps/emqx_gateway/src/emqx_gateway_schema.erl +++ b/apps/emqx_gateway/src/emqx_gateway_schema.erl @@ -250,7 +250,12 @@ fields(lwm2m) -> sc( binary(), #{ - default => emqx:etc_file("lwm2m_xml"), + %% since this is not packaged with emqx, nor + %% present in the packages, we must let the user + %% specify it rather than creating a dynamic + %% default (especially difficult to handle when + %% generating docs). + example => <<"/etc/emqx/lwm2m_xml">>, required => true, desc => ?DESC(lwm2m_xml_dir) } From 198ddda8bc4d83de5776bbf47e28c18a2a4ee3c0 Mon Sep 17 00:00:00 2001 From: Thales Macedo Garitezi Date: Mon, 31 Oct 2022 14:02:55 -0300 Subject: [PATCH 2/2] docs(status_api): add remark about feature introduction versions --- apps/emqx_exhook/src/emqx_exhook.app.src | 2 +- apps/emqx_management/i18n/emqx_mgmt_api_status_i18n.conf | 8 +++++++- 2 files changed, 8 insertions(+), 2 deletions(-) diff --git a/apps/emqx_exhook/src/emqx_exhook.app.src b/apps/emqx_exhook/src/emqx_exhook.app.src index 3f844f61d..4e8abef81 100644 --- a/apps/emqx_exhook/src/emqx_exhook.app.src +++ b/apps/emqx_exhook/src/emqx_exhook.app.src @@ -1,7 +1,7 @@ %% -*- mode: erlang -*- {application, emqx_exhook, [ {description, "EMQX Extension for Hook"}, - {vsn, "5.0.5"}, + {vsn, "5.0.6"}, {modules, []}, {registered, []}, {mod, {emqx_exhook_app, []}}, diff --git a/apps/emqx_management/i18n/emqx_mgmt_api_status_i18n.conf b/apps/emqx_management/i18n/emqx_mgmt_api_status_i18n.conf index 9c09806cd..fae17b35d 100644 --- a/apps/emqx_management/i18n/emqx_mgmt_api_status_i18n.conf +++ b/apps/emqx_management/i18n/emqx_mgmt_api_status_i18n.conf @@ -8,13 +8,19 @@ emqx_mgmt_api_status { "Returns status code 200 if the EMQX application is up and running, " "503 otherwise." "\n" + "This API was introduced in v5.0.10." + "\n" "The GET `/status` endpoint (without the `/api/...` prefix) is also an alias" - " to this endpoint and works in the same way." + " to this endpoint and works in the same way. This alias has been available since" + " v5.0.0." zh: "作为节点的健康检查。 返回一个纯文本的响应，描述节点的状态。\n" "\n" "如果 EMQX 应用程序已经启动并运行，返回状态代码 200，否则返回 503。\n" "\n" + "这个API是在v5.0.10中引入的。" + "\n" "GET `/status`端点（没有`/api/...`前缀）也是这个端点的一个别名，工作方式相同。" + " 这个别名从v5.0.0开始就有了。" } }