This is an automated email from the ASF dual-hosted git repository.
spacewander pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/apisix.git
The following commit(s) were added to refs/heads/master by this push:
new 2be3235 docs: fix the title level of API sections (#5939)
2be3235 is described below
commit 2be323564e37a7d7fe16ae4a1675e085f1867120
Author: 罗泽轩 <[email protected]>
AuthorDate: Mon Dec 27 21:32:27 2021 +0800
docs: fix the title level of API sections (#5939)
---
docs/en/latest/plugin-develop.md | 110 +++++++++++++++++++--------------------
docs/zh/latest/plugin-develop.md | 98 +++++++++++++++++-----------------
2 files changed, 104 insertions(+), 104 deletions(-)
diff --git a/docs/en/latest/plugin-develop.md b/docs/en/latest/plugin-develop.md
index c36f5bc..cc629e6 100644
--- a/docs/en/latest/plugin-develop.md
+++ b/docs/en/latest/plugin-develop.md
@@ -32,10 +32,10 @@ title: Plugin Develop
- [implement the logic](#implement-the-logic)
- [conf parameter](#conf-parameter)
- [ctx parameter](#ctx-parameter)
+- [Register public API](#register-public-api)
+- [Register control API](#register-control-api)
- [write test case](#write-test-case)
- [Attach the test-nginx execution
process:](#attach-the-test-nginx-execution-process)
- - [Register public API](#register-public-api)
- - [Register control API](#register-control-api)
This documentation is about developing plugin in Lua. For other languages,
see [external plugin](./external-plugin.md).
@@ -388,6 +388,59 @@ function _M.access(conf, ctx)
end
```
+## Register public API
+
+A plugin can register API which exposes to the public. Take jwt-auth plugin as
an example, this plugin registers `GET /apisix/plugin/jwt/sign` to allow client
to sign its key:
+
+```lua
+local function gen_token()
+ --...
+end
+
+function _M.api()
+ return {
+ {
+ methods = {"GET"},
+ uri = "/apisix/plugin/jwt/sign",
+ handler = gen_token,
+ }
+ }
+end
+```
+
+Note that the public API is exposed to the public.
+You may need to use [interceptors](plugin-interceptors.md) to protect it.
+
+## Register control API
+
+If you only want to expose the API to the localhost or intranet, you can
expose it via [Control API](./control-api.md).
+
+Take a look at example-plugin plugin:
+
+```lua
+local function hello()
+ local args = ngx.req.get_uri_args()
+ if args["json"] then
+ return 200, {msg = "world"}
+ else
+ return 200, "world\n"
+ end
+end
+
+
+function _M.control_api()
+ return {
+ {
+ methods = {"GET"},
+ uris = {"/v1/plugin/example-plugin/hello"},
+ handler = hello,
+ }
+ }
+end
+```
+
+If you don't change the default control API configuration, the plugin will be
expose `GET /v1/plugin/example-plugin/hello` which can only be accessed via
`127.0.0.1`.
+
## write test case
For functions, write and improve the test cases of various dimensions, do a
comprehensive test for your plugin! The
@@ -441,56 +494,3 @@ According to the path we configured in the makefile and
some configuration items
framework will assemble into a complete nginx.conf file. "__t/servroot__" is
the working directory of Nginx and start the
Nginx instance. according to the information provided by the test case,
initiate the http request and check that the
return items of HTTP include HTTP status, HTTP response header, HTTP response
body and so on.
-
-### Register public API
-
-A plugin can register API which exposes to the public. Take jwt-auth plugin as
an example, this plugin registers `GET /apisix/plugin/jwt/sign` to allow client
to sign its key:
-
-```lua
-local function gen_token()
- --...
-end
-
-function _M.api()
- return {
- {
- methods = {"GET"},
- uri = "/apisix/plugin/jwt/sign",
- handler = gen_token,
- }
- }
-end
-```
-
-Note that the public API is exposed to the public.
-You may need to use [interceptors](plugin-interceptors.md) to protect it.
-
-### Register control API
-
-If you only want to expose the API to the localhost or intranet, you can
expose it via [Control API](./control-api.md).
-
-Take a look at example-plugin plugin:
-
-```lua
-local function hello()
- local args = ngx.req.get_uri_args()
- if args["json"] then
- return 200, {msg = "world"}
- else
- return 200, "world\n"
- end
-end
-
-
-function _M.control_api()
- return {
- {
- methods = {"GET"},
- uris = {"/v1/plugin/example-plugin/hello"},
- handler = hello,
- }
- }
-end
-```
-
-If you don't change the default control API configuration, the plugin will be
expose `GET /v1/plugin/example-plugin/hello` which can only be accessed via
`127.0.0.1`.
diff --git a/docs/zh/latest/plugin-develop.md b/docs/zh/latest/plugin-develop.md
index e8b5b32..62ddc11 100644
--- a/docs/zh/latest/plugin-develop.md
+++ b/docs/zh/latest/plugin-develop.md
@@ -31,10 +31,10 @@ title: 插件开发
- [编写执行逻辑](#编写执行逻辑)
- [conf 参数](#conf-参数)
- [ctx 参数](#ctx-参数)
+- [注册公共接口](#注册公共接口)
+- [注册控制接口](#注册控制接口)
- [编写测试用例](#编写测试用例)
- [附上 test-nginx 执行流程](#附上-test-nginx-执行流程)
- - [注册公共接口](#注册公共接口)
- - [注册控制接口](#注册控制接口)
## 检查外部依赖
@@ -308,52 +308,7 @@ function _M.access(conf, ctx)
end
```
-## 编写测试用例
-
-针对功能，完善各种维度的测试用例，对插件做个全方位的测试吧！插件的测试用例，都在 __t/plugin__ 目录下，可以前去了解。
-项目测试框架采用的 [****test-nginx****](https://github.com/openresty/test-nginx) 。
-一个测试用例 __.t__ 文件，通常用 \__DATA\__ 分割成 序言部分 和 数据部分。这里我们简单介绍下数据部分，
-也就是真正测试用例的部分，仍然以 key-auth 插件为例：
-
-```perl
-=== TEST 1: sanity
---- config
- location /t {
- content_by_lua_block {
- local plugin = require("apisix.plugins.key-auth")
- local ok, err = plugin.check_schema({key = 'test-key'},
core.schema.TYPE_CONSUMER)
- if not ok then
- ngx.say(err)
- end
-
- ngx.say("done")
- }
- }
---- request
-GET /t
---- response_body
-done
---- no_error_log
-[error]
-```
-
-一个测试用例主要有三部分内容：
-
-- 程序代码： Nginx location 的配置内容
-- 输入： http 的 request 信息
-- 输出检查： status ，header ，body ，error_log 检查
-
-这里请求 __/t__ ，经过配置文件 __location__ ，调用 __content_by_lua_block__ 指令完成 lua
的脚本，最终返回。
-用例的断言是 response_body 返回 "done"，__no_error_log__ 表示会对 Nginx 的 error.log 检查，
-必须没有 ERROR 级别的记录。
-
-### 附上 test-nginx 执行流程
-
-根据我们在 Makefile 里配置的 PATH，和每一个 __.t__ 文件最前面的一些配置项，框架会组装成一个完整的 nginx.conf 文件，
-__t/servroot__ 会被当成 Nginx 的工作目录，启动 Nginx 实例。根据测试用例提供的信息，发起 http 请求并检查 http
的返回项，
-包括 http status，http response header， http response body 等。
-
-### 注册公共接口
+## 注册公共接口
插件可以注册暴露给公网的接口。以 jwt-auth 插件为例，这个插件为了让客户端能够签名，注册了 `GET
/apisix/plugin/jwt/sign` 这个接口:
@@ -376,7 +331,7 @@ end
注意注册的接口会暴露到外网。
你可能需要使用 [interceptors](plugin-interceptors.md) 来保护它。
-### 注册控制接口
+## 注册控制接口
如果你只想暴露 API 到 localhost 或内网，你可以通过 [Control API](./control-api.md) 来暴露它。
@@ -405,3 +360,48 @@ end
```
如果你没有改过默认的 control API 配置，这个插件暴露的 `GET /v1/plugin/example-plugin/hello` API
只有通过 `127.0.0.1` 才能访问它。
+
+## 编写测试用例
+
+针对功能，完善各种维度的测试用例，对插件做个全方位的测试吧！插件的测试用例，都在 __t/plugin__ 目录下，可以前去了解。
+项目测试框架采用的 [****test-nginx****](https://github.com/openresty/test-nginx) 。
+一个测试用例 __.t__ 文件，通常用 \__DATA\__ 分割成 序言部分 和 数据部分。这里我们简单介绍下数据部分，
+也就是真正测试用例的部分，仍然以 key-auth 插件为例：
+
+```perl
+=== TEST 1: sanity
+--- config
+ location /t {
+ content_by_lua_block {
+ local plugin = require("apisix.plugins.key-auth")
+ local ok, err = plugin.check_schema({key = 'test-key'},
core.schema.TYPE_CONSUMER)
+ if not ok then
+ ngx.say(err)
+ end
+
+ ngx.say("done")
+ }
+ }
+--- request
+GET /t
+--- response_body
+done
+--- no_error_log
+[error]
+```
+
+一个测试用例主要有三部分内容：
+
+- 程序代码： Nginx location 的配置内容
+- 输入： http 的 request 信息
+- 输出检查： status ，header ，body ，error_log 检查
+
+这里请求 __/t__ ，经过配置文件 __location__ ，调用 __content_by_lua_block__ 指令完成 lua
的脚本，最终返回。
+用例的断言是 response_body 返回 "done"，__no_error_log__ 表示会对 Nginx 的 error.log 检查，
+必须没有 ERROR 级别的记录。
+
+### 附上 test-nginx 执行流程
+
+根据我们在 Makefile 里配置的 PATH，和每一个 __.t__ 文件最前面的一些配置项，框架会组装成一个完整的 nginx.conf 文件，
+__t/servroot__ 会被当成 Nginx 的工作目录，启动 Nginx 实例。根据测试用例提供的信息，发起 http 请求并检查 http
的返回项，
+包括 http status，http response header， http response body 等。
