docs: add public-api related content #6218

bzp2010 · 2022-01-27T11:12:19Z

What this PR does / why we need it:

Add public-api related documents, and remove obsolete content regarding plugin interceptors and plugin development.

Pre-submission checklist:

Did you explain what problem does this PR solve? Or what new features have been added?
Have you added corresponding test cases?
Have you modified the corresponding document?
Is this PR backward compatible? If it is not backward compatible, please discuss on the mailing list first

docs/en/latest/plugins/prometheus.md

docs/en/latest/plugins/public-api.md

docs/zh/latest/plugins/batch-requests.md

docs/zh/latest/plugins/jwt-auth.md

docs/zh/latest/plugins/node-status.md

docs/zh/latest/plugins/wolf-rbac.md

shuaijinchao · 2022-01-28T01:21:07Z

docs/zh/latest/plugin-develop.md

@@ -326,8 +326,7 @@ function _M.api()
 end
 ```

-注意注册的接口会暴露到外网。
-你可能需要使用 [interceptors](plugin-interceptors.md) 来保护它。
+注意，注册的接口将不会默认暴露，您需要使用[public-api 插件](plugins/public-api.md)来暴露它。


Suggested change

注意，注册的接口将不会默认暴露，您需要使用[public-api 插件](plugins/public-api.md)来暴露它。

注意，注册的接口将不会默认暴露，需要使用[public-api 插件](plugins/public-api.md)来暴露它。

the use of honorifics for personal pronouns is not required in documentation.

fixed, Other personal pronouns in the md file of this PR design have also been removed.

ping @shuaijinchao

shuaijinchao · 2022-01-28T01:22:04Z

docs/zh/latest/plugins/prometheus.md


 ```
 plugin_attr:
  prometheus:
    enable_export_server: false
 ```

+同时，您还需要使用 [public-api](public-api.md) 插件来暴露它。


Suggested change

同时，您还需要使用 [public-api](public-api.md) 插件来暴露它。

同时，需要使用 [public-api](public-api.md) 插件来暴露它。

docs/en/latest/plugins/public-api.md

spacewander · 2022-02-07T04:48:50Z

docs/en/latest/plugins/public-api.md

+The `public-api` plugin is used to enhance the plugin public API access control.
+When current users develop custom plugins, they can register some public APIs for fixed functionality, such as the `/apisix/plugin/jwt/sign` API in `jwt-auth`. These APIs can only apply limited plugins for access control (currently only `ip-restriction`) by way of plugin interceptors.
+
+With the `public-api` plugin, we put the all public API into general HTTP API router, which is consistent with the normal route registered by the user and can apply any plugin. The public API added in the user plugin is no longer open by default by APISIX, but the user manually configures the route for it, and the user can configure any uri and plugin.


Suggested change

With the `public-api` plugin, we put the all public API into general HTTP API router, which is consistent with the normal route registered by the user and can apply any plugin. The public API added in the user plugin is no longer open by default by APISIX, but the user manually configures the route for it, and the user can configure any uri and plugin.

With the `public-api` plugin, we put all public API into the general HTTP API router, which is consistent with the normal route registered by the user and can apply any plugin. The public API added in the user plugin is no longer open by default by APISIX, but the user manually configures the route for it, and the user can configure any uri and plugin.

spacewander · 2022-02-07T04:53:20Z

docs/zh/latest/plugins/node-status.md

@@ -40,7 +40,7 @@ title: node-status

 ## 插件接口

-插件增加接口 `/apisix/status`，可通过 [interceptors](../plugin-interceptors.md) 保护该接口。
+插件增加接口 `/apisix/status`，需要通过 [public-api](public-api.md) 插件来暴露它。


Let's update the link to point to English version like

apisix/docs/zh/latest/plugins/kafka-logger.md

Line 183 in 48e8a1e

| log_format | object | 可选 | {"host": "$host", "@timestamp": "$time_iso8601", "client_ip": "$remote_addr"} | | 以 JSON 格式的键值对来声明日志格式。对于值部分，仅支持字符串。如果是以 `$` 开头，则表明是要获取 [APISIX 变量](../../../en/latest/apisix-variable.md) 或 [Nginx 内置变量](http://nginx.org/en/docs/varindex.html)。特别的，**该设置是全局生效的**，意味着指定 log_format 后，将对所有绑定 http-logger 的 Route 或 Service 生效。 |

Hi, @spacewander.

As currently used, it renders properly on our official website (when no language-specific localization documents are returned to English), and if we modify it directly, it will cause confusion on the official website, i.e. some multilingual documents will be all linked back to the English version.
It seems like we can't have it both ways, but I think it's more important to make sure the content on the official website is always available in the right way than to use the md file to read it directly.

Currently there is no Chinese documentation for the public-api plugin, if you think it is really necessary to change it, I will do so.

How about using English only in this PR? After it gets merged, @guoqqqi and @Baoyuantop could help to translate 🤔

@bzp2010 @juzhiyuan
We already do this in other loggers. Although someone else can translate it later, but we should not invent another way to handle it, and merge a PR which will create known broken links.

@spacewander updated

juzhiyuan

LGTM

bzp2010 added 2 commits January 27, 2022 19:08

docs: add public-api plugin

a2870f9

docs: add category

88358c7

bzp2010 self-assigned this Jan 27, 2022

bzp2010 added 6 commits January 27, 2022 19:13

fix: lint EOL

1ff4949

docs: improve public-api

dd24887

docs: remove plugin interceptors from category

b446dad

docs: update plugin develop

716a0f3

docs: remove interceptor for other plugins

691dc6f

docs: remove plugin interceptors

25c0ab9

bzp2010 requested review from spacewander, juzhiyuan, shuaijinchao and tzssangglass January 27, 2022 11:54

bzp2010 marked this pull request as ready for review January 27, 2022 11:54

juzhiyuan reviewed Jan 27, 2022

View reviewed changes

shuaijinchao reviewed Jan 28, 2022

View reviewed changes

tzssangglass reviewed Jan 28, 2022

View reviewed changes

docs/en/latest/plugins/public-api.md Show resolved Hide resolved

docs/en/latest/plugins/public-api.md Show resolved Hide resolved

docs/en/latest/plugins/public-api.md Show resolved Hide resolved

docs: remove personal pronouns and "may"

841295a

bzp2010 requested review from juzhiyuan, shuaijinchao and tzssangglass January 28, 2022 04:56

bzp2010 added 3 commits January 28, 2022 16:17

docs: add data plane default port

e40b582

docs: fix typo

f30af25

Merge branch 'master' into doc-public-api-relative

620c1a0

juzhiyuan reviewed Feb 7, 2022

View reviewed changes

docs/en/latest/plugins/public-api.md Outdated Show resolved Hide resolved

spacewander reviewed Feb 7, 2022

View reviewed changes

tzssangglass approved these changes Feb 7, 2022

View reviewed changes

docs: update description

2c1c38b

bzp2010 requested review from spacewander and juzhiyuan February 7, 2022 13:24

juzhiyuan approved these changes Feb 7, 2022

View reviewed changes

LiteSun approved these changes Feb 8, 2022

View reviewed changes

shuaijinchao approved these changes Feb 8, 2022

View reviewed changes

docs: update broken links

e5c5994

spacewander approved these changes Feb 8, 2022

View reviewed changes

spacewander merged commit ec0fc2c into apache:master Feb 8, 2022

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

docs: add public-api related content #6218

docs: add public-api related content #6218

bzp2010 commented Jan 27, 2022

shuaijinchao Jan 28, 2022

bzp2010 Jan 28, 2022

bzp2010 Jan 28, 2022

bzp2010 Jan 28, 2022

shuaijinchao Jan 28, 2022

bzp2010 Jan 28, 2022

spacewander Feb 7, 2022

bzp2010 Feb 7, 2022

spacewander Feb 7, 2022

bzp2010 Feb 7, 2022

juzhiyuan Feb 7, 2022

spacewander Feb 8, 2022

bzp2010 Feb 8, 2022

juzhiyuan left a comment

	注意，注册的接口将不会默认暴露，您需要使用[public-api 插件](plugins/public-api.md)来暴露它。
	注意，注册的接口将不会默认暴露，需要使用[public-api 插件](plugins/public-api.md)来暴露它。

	同时，您还需要使用 [public-api](public-api.md) 插件来暴露它。
	同时，需要使用 [public-api](public-api.md) 插件来暴露它。

	With the `public-api` plugin, we put the all public API into general HTTP API router, which is consistent with the normal route registered by the user and can apply any plugin. The public API added in the user plugin is no longer open by default by APISIX, but the user manually configures the route for it, and the user can configure any uri and plugin.
	With the `public-api` plugin, we put all public API into the general HTTP API router, which is consistent with the normal route registered by the user and can apply any plugin. The public API added in the user plugin is no longer open by default by APISIX, but the user manually configures the route for it, and the user can configure any uri and plugin.

docs: add public-api related content #6218

docs: add public-api related content #6218

Conversation

bzp2010 commented Jan 27, 2022

What this PR does / why we need it:

Pre-submission checklist:

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

juzhiyuan left a comment

Choose a reason for hiding this comment