This is an automated email from the ASF dual-hosted git repository.
wenming pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/incubator-apisix.git
The following commit(s) were added to refs/heads/master by this push:
new 08093c4 doc: Adding doc on how to add a prefix to the route (#1238)
08093c4 is described below
commit 08093c49e81d016fc5b699ad2bd76bbbc624fc89
Author: Nirojan Selvanathan <[email protected]>
AuthorDate: Fri Mar 13 01:34:02 2020 +0100
doc: Adding doc on how to add a prefix to the route (#1238)
---
doc/getting-started.md | 28 ++++++++++++++++++++++++-
doc/plugin-develop.md | 56 +++++++++++++++++++++++++-------------------------
2 files changed, 55 insertions(+), 29 deletions(-)
diff --git a/doc/getting-started.md b/doc/getting-started.md
index 01b4d03..640226d 100644
--- a/doc/getting-started.md
+++ b/doc/getting-started.md
@@ -212,13 +212,39 @@ Use the command below to securely access the endpoint now.
curl -i -X GET http://127.0.0.1:9080/get -H "Host: httpbin.org" -H 'apikey:
superSecretAPIKey'
```
+## Add a prefix to the route (Optional)
+
+Now lets say you want to add a prefix (eg: samplePrefix) to the route and do
not want to use the `host` header then you can use
+the proxy rewrite plugin to do it.
+
+```bash
+curl http://127.0.0.1:9080/apisix/admin/routes/5 -H 'X-API-KEY:
edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
+{
+ "uri": "/samplePrefix/get",
+ "plugins": {
+ "proxy-rewrite": {
+ "scheme": "https",
+ "regex_uri": ["^/samplePrefix/get(.*)", "/get$1"]
+ },
+ "key-auth": {}
+ },
+ "upstream_id": 50
+}'
+```
+
+Now you can invoke the route with the following command:
+
+```bash
+curl -i -X GET http://127.0.0.1:9080/samplePrefix/get?param1=foo¶m2=bar -H
'apikey: superSecretAPIKey'
+```
+
### Troubleshooting
- Make sure the required ports are not being used by other systems/processes
(The default ports are: 9080, 9443, 2379).
The following is the command to kill a process which is listening to a
specific port (in unix based systems).
```bash
- fuser -k 9443/tcp
+ sudo fuser -k 9443/tcp
```
- If the docker container is continuously restarting/failing, login to the
container and observe the logs to diagnose the issue.
diff --git a/doc/plugin-develop.md b/doc/plugin-develop.md
index fc22f50..57af2dd 100644
--- a/doc/plugin-develop.md
+++ b/doc/plugin-develop.md
@@ -29,8 +29,8 @@
## check dependencies
-if you have dependencies on external libraries , check the dependent items .
if your plugin needs to use shared memory , it
- needs to declare in __bin/apisix__ , for example :
+if you have dependencies on external libraries, check the dependent items. if
your plugin needs to use shared memory, it
+ needs to declare in __bin/apisix__, for example :
```nginx
lua_shared_dict plugin-limit-req 10m;
@@ -46,19 +46,19 @@ if you have dependencies on external libraries , check the
dependent items . if
lua_shared_dict introspection 10m; # cache for JWT verification
results
```
-The plugin itself provides the init method . It is convenient for plugins to
perform some initialization after
- the plugin is loaded .
+The plugin itself provides the init method. It is convenient for plugins to
perform some initialization after
+ the plugin is loaded.
-Note : if the dependency of some plugin needs to be initialized when Nginx
start , you may need to add logic to the initialization
- method "http_init" in the file __Lua/apifix.lua__ , And you may need to
add some processing on generated part of Nginx
- configuration file in __bin/apisix__ file . but it is easy to have an
impact on the overall situation according to the
- existing plugin mechanism, we do not recommend this unless you have a
complete grasp of the code .
+Note : if the dependency of some plugin needs to be initialized when Nginx
start, you may need to add logic to the initialization
+ method "http_init" in the file __Lua/apifix.lua__, And you may need to
add some processing on generated part of Nginx
+ configuration file in __bin/apisix__ file. but it is easy to have an
impact on the overall situation according to the
+ existing plugin mechanism, we do not recommend this unless you have a
complete grasp of the code.
## name and config
-determine the name and priority of the plugin , and add to conf/config.yaml .
For example , for the key-auth plugin ,
+determine the name and priority of the plugin, and add to conf/config.yaml.
For example, for the key-auth plugin,
you need to specify the plugin name in the code (the name is the unique
identifier of the plugin and cannot be
- duplicate) , you can see the code in file
"__lua/apisix/plugins/key-auth.lua__" :
+ duplicate), you can see the code in file
"__lua/apisix/plugins/key-auth.lua__" :
```lua
local plugin_name = "key-auth"
@@ -74,7 +74,7 @@ determine the name and priority of the plugin , and add to
conf/config.yaml . Fo
Note : The priority of the new plugin cannot be the same as the priority of
any existing plugin.
-in the "__conf/config.yaml__" configuration file , the enabled plugins (all
specified by plugin name) are listed .
+in the "__conf/config.yaml__" configuration file, the enabled plugins (all
specified by plugin name) are listed.
```yaml
plugins: # plugin list
@@ -96,11 +96,11 @@ plugins: # plugin list
- redirect
```
-Note : the order of the plugins is not related to the order of execution .
+Note : the order of the plugins is not related to the order of execution.
## schema and check
-Write [Json Schema](https://json-schema.org) descriptions and check functions.
similarly , take the key-auth plugin as an example to see its
+Write [Json Schema](https://json-schema.org) descriptions and check functions.
similarly, take the key-auth plugin as an example to see its
configuration data :
```json
@@ -109,7 +109,7 @@ Write [Json Schema](https://json-schema.org) descriptions
and check functions. s
}
```
-The configuration data of the plugin is relatively simple . Only one attribute
named key is supported . Let's look
+The configuration data of the plugin is relatively simple. Only one attribute
named key is supported. Let's look
at its schema description :
```lua
@@ -121,7 +121,7 @@ at its schema description :
}
```
-At the same time, we need to implement the __check_schema(conf)__ method to
complete the specification verification .
+At the same time, we need to implement the __check_schema(conf)__ method to
complete the specification verification.
```lua
function _M.check_schema(conf)
@@ -129,16 +129,16 @@ At the same time, we need to implement the
__check_schema(conf)__ method to comp
end
```
-Note: the project has provided the public method "__core.schema.check__" ,
which can be used directly to complete JSON
-verification .
+Note: the project has provided the public method "__core.schema.check__",
which can be used directly to complete JSON
+verification.
## choose phase to run
-Determine which phase to run , generally access or rewrite . If you don't know
the [Openresty life
cycle](https://openresty-reference.readthedocs.io/en/latest/Directives/) , it's
-recommended to know it in advance . For example key-auth is an authentication
plugin , thus the authentication should be completed
+Determine which phase to run, generally access or rewrite. If you don't know
the [Openresty life
cycle](https://openresty-reference.readthedocs.io/en/latest/Directives/), it's
+recommended to know it in advance. For example key-auth is an authentication
plugin, thus the authentication should be completed
before forwarding the request to any upstream service. Therefore, the plugin
can be executed in the rewrite and access phases.
-In APISIX, the authentication logic is implemented in the rewrite phase .
Generally, IP access and interface
-permission are completed in the access phase .
+In APISIX, the authentication logic is implemented in the rewrite phase.
Generally, IP access and interface
+permission are completed in the access phase.
The following code snippet shows how to implement any logic relevant to the
plugin in the Openresty log phase.
@@ -150,15 +150,15 @@ end
## implement the logic
-Write the logic of the plugin in the corresponding phase .
+Write the logic of the plugin in the corresponding phase.
## write test case
-For functions , write and improve the test cases of various dimensions , do a
comprehensive test for your plugin ! The
+For functions, write and improve the test cases of various dimensions, do a
comprehensive test for your plugin ! The
test cases of plugins are all in the "__t/plugin__" directory. You can go
ahead to find out. APISIX uses
-[****test-nginx****](https://github.com/openresty/test-nginx) as the test
framework. A test case, .t file is usually
-divided into prologue and data parts by \__data\__ . Here we will briefly
introduce the data part, that is, the part
-of the real test case . For example, the key-auth plugin :
+[****test-nginx****](https://github.com/openresty/test-nginx) as the test
framework. A test case,.t file is usually
+divided into prologue and data parts by \__data\__. Here we will briefly
introduce the data part, that is, the part
+of the real test case. For example, the key-auth plugin :
```perl
=== TEST 1: sanity
@@ -187,7 +187,7 @@ A test case consists of three parts :
- __Input__ : http request information
- __Output check__ : status, header, body, error log check
-When we request __/t__ , which config in the configuration file , the Nginx
will call "__content_by_lua_block__" instruction to
+When we request __/t__, which config in the configuration file, the Nginx will
call "__content_by_lua_block__" instruction to
complete the Lua script, and finally return. The assertion of the use case is
response_body return "done",
"__no_error_log__" means to check the "__error.log__" of Nginx. There must be
no ERROR level record. The log files for the unit test
are located in the following folder: 't/servroot/logs'.
@@ -199,4 +199,4 @@ Refer the following [document](how-to-build.md#test) to
setup the testing framew
According to the path we configured in the makefile and some configuration
items at the front of each __.t__ file, the
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 .
+return items of HTTP include HTTP status, HTTP response header, HTTP response
body and so on.
