docs: improve `plugin-develop` docs by ctxinf · Pull Request #12242 · apache/apisix

ctxinf · 2025-05-22T06:08:34Z

Description

I encountered some difficulties while following the plugin-develop documentation during development:

The structure of the document was confusing and not clearly organized; it didn’t progress from basic to advanced concepts.
Some critical parts were not explained. help request: custom plugin failed to load plugin [demo] err: module 'apisix.plugins.demo' not found: #11835 (comment)

Therefore, I restructured the overall layout, provided more detailed explanations in some sections, and added some relevant resources.

Which issue(s) this PR fixes:

Fixes #

Checklist

I have explained the need for this PR and the problem it solves
I have explained the changes or the new features added to this PR
I have added tests corresponding to this change
I have updated the documentation to reflect this change
I have verified that this change is backward compatible (If not, please discuss on the APISIX mailing list first)

kayx23 · 2025-05-23T08:54:30Z

Please resolve lint errors.

kayx23 · 2025-05-27T08:49:55Z

+## Where to put your plugins

-There are two ways to add new features based on APISIX.
+Setup the `extra_lua_path` in `conf/config.yaml` to load your own code (or `extra_lua_cpath` for compiled .so or .dll file).


Suggested change

Setup the `extra_lua_path` in `conf/config.yaml` to load your own code (or `extra_lua_cpath` for compiled .so or .dll file).

Use the `extra_lua_path` parameter in `conf/config.yaml` file to load your custom plugin code (or use `extra_lua_cpath` for compiled `.so` or `.dll` file).

kayx23 · 2025-05-27T08:51:59Z

-│   └── apisix
-│       ├── plugins
-│       │   └── 3rd-party.lua
-│       └── stream


Maybe leave the stream and mention in text that if you would like to load a custom stream (L4) plugin, this is how it should structured. My concern is that once the stream folder is removed, it is not documented anywhere else.

I know nothing about the stream folder, please revise this section yourself.

kayx23 · 2025-05-27T08:53:02Z

 :::note

-If you need to customize the directory of plugin, please create a subdirectory of `/apisix/plugins` under this directory.
+The directory (`/path/to/example`) must contain the `/apisix/plugins` subdirectory.


How about

Suggested change

The directory (`/path/to/example`) must contain the `/apisix/plugins` subdirectory.

The directory (`/path/to/example`) must contain the `/apisix/plugins` subdirectory for L7 plugins.

kayx23 · 2025-05-27T08:53:38Z


-if you have dependencies on external libraries, check the dependent items. if your plugin needs to use shared memory, it
-needs to declare via [customizing Nginx configuration](./customize-nginx-configuration.md), for example :
+Once the plugins configuration is defined in `conf/config.yaml`, the new plugins list will replace the default configuration instead of merging. Therefore, when defining the `plugins` field, make sure to include the built-in plugins that are being used. To maintain consistency with the default behavior, you can include all the default enabled plugins defined in **apisix/cli/config.lua**.


Suggested change

Once the plugins configuration is defined in `conf/config.yaml`, the new plugins list will replace the default configuration instead of merging. Therefore, when defining the `plugins` field, make sure to include the built-in plugins that are being used. To maintain consistency with the default behavior, you can include all the default enabled plugins defined in **apisix/cli/config.lua**.

Once the plugins configuration is defined in `conf/config.yaml`, the new plugins list will replace the default configuration instead of merging. Therefore, when defining the `plugins` field, make sure to include the built-in plugins that are being used. To maintain consistency with the default behavior, you can include all the default enabled plugins defined in `apisix/cli/config.lua`.

kayx23 · 2025-05-27T08:54:38Z

-method "http_init" in the file __apisix/init.lua__, and you may need to add some processing on generated part of Nginx
-configuration file in __apisix/cli/ngx_tpl.lua__ 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**.
+The [example-plugin](https://github.com/apache/apisix/blob/master/apisix/plugins/example-plugin.lua) plugin (local location: **apisix/plugins/example-plugin.lua**) provides an example.


Suggested change

The [example-plugin](https://github.com/apache/apisix/blob/master/apisix/plugins/example-plugin.lua) plugin (local location: **apisix/plugins/example-plugin.lua**) provides an example.

The [`example-plugin`](https://github.com/apache/apisix/blob/master/apisix/plugins/example-plugin.lua) plugin in this repo provides an example.

kayx23 · 2025-05-27T08:59:58Z

+
+## Check external dependencies
+
+If you have dependencies on external libraries, check the dependent items. if your plugin needs to use shared memory, it


Suggested change

If you have dependencies on external libraries, check the dependent items. if your plugin needs to use shared memory, it

If you have dependencies on external libraries, check the dependent items. If your plugin needs to use shared memory, it

kayx23 · 2025-05-27T09:00:41Z

+Parameters can be stored encrypted by specifying `encrypt_fields = {"password"}` in the `schema`. APISIX will provide the following functionality.
+
+- When adding and updating resources via the `Admin API`, APISIX automatically encrypts the parameters declared in `encrypt_fields` and stores them in etcd
+- When fetching resources via the `Admin API` and when running the plugin, APISIX automatically decrypts the parameters declared in `encrypt_fields`


No need to put Admin API in line.

kayx23 · 2025-05-27T09:05:44Z

+
+::: note
+APISIX version is not less than 3.1
+:::


I think this sentence can be removed since the doc (next) will be released when 3.13 is out. 3.1. is way back in the days already.

If you think this note is still relevant, there is a formatting issue: it should be :::note (without the space); otherwise the admonition will not be rendered properly.

kayx23 · 2025-05-27T09:18:22Z

+
+How to enable this feature?
+
+Enable `data_encryption` in `config.yaml`.


This feature is enabled by default now

kayx23 · 2025-05-27T09:19:59Z

+
+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 __apisix/init.lua__, and you may need to add some processing on generated part of Nginx
+configuration file in __apisix/cli/ngx_tpl.lua__ file. But it is easy to have an impact on the overall situation according to the


Put the paths above in inline code, instead of bolding them?

kayx23 · 2025-06-03T04:37:39Z

-In addition, if the plugin needs to use some metadata, we can define the plugin `metadata_schema`, and then we can dynamically manage these metadata through the `Admin API`. Example:
+:::
+
+The input parameter **schema_type** is used to distinguish between different schemas types. For example, many plugins need to use some [metadata](./terminology/plugin-metadata.md), so they define the plugin's `metadata_schema`. Another example, the [key-auth](https://github.com/apache/apisix/blob/master/apisix/plugins/key-auth.lua) plugin needs to provide a `consumer_schema` to check the configuration of the `plugins` attribute of the `consumer` resource in order to be used with the [Consumer](./admin-api.md#consumer) resource.


A couple issues regarding this rearrangement:

it is easier to read if this info is moved down to its corresponding content:

Missing information - consumer_schema was removed in this PR. Why?

For the reader, the purpose of this paragraph is simply to indicate that the function can be used to check different schemas, so I removed the excessive content, including consumer_schema. However, consumer_schema might still be worth keeping.
I have reorganized this paragraph.

kayx23

Just this comment and there are a few previous comments that were not addressed. See https://github.com/apache/apisix/pull/12242/files Other changes look good

kayx23 · 2025-06-06T09:21:10Z

-To validate the configuration, the plugin uses a schema like this:
+Another example, the [key-auth](https://github.com/apache/apisix/blob/master/apisix/plugins/key-auth.lua) plugin needs to provide a `consumer_schema` to check the configuration of the `plugins` attribute of the `consumer` resource in order to be used with the [Consumer](./admin-api.md#consumer) resource.

 ```lua


Can put the title like this:

Suggested change

```lua

```lua title="key-auth.lua"

and remove the comment in the code block:

The missing parts have been adddressed.

Except for the stream plugin part(including the descriptions of L4 and L7). Since I can only find related content in the blogs, I thought it's better that the maintainers provide detailed content for this part.

docs: improve plugin-develop docs

f146f0c

dosubot Bot added size:XL This PR changes 500-999 lines, ignoring generated files. doc Documentation things labels May 22, 2025

docs: fix plugin-develop doc lint errors

aa49746

kayx23 self-requested a review May 24, 2025 09:56

kayx23 reviewed May 27, 2025

View reviewed changes

ctxinf added 3 commits May 28, 2025 12:35

docs: improve content based on maintainer's suggestions

60643b3

docs: fix Chinese copywriting error

dbab931

docs: fix Chinese copywriting error again

f2ac774

kayx23 reviewed Jun 3, 2025

View reviewed changes

docs: improve consumer schema part

8843c77

kayx23 reviewed Jun 6, 2025

View reviewed changes

supplement some missed revisions

55a3aa1

kayx23 approved these changes Jun 8, 2025

View reviewed changes

Baoyuantop approved these changes Jun 9, 2025

View reviewed changes

Baoyuantop requested a review from moonming June 9, 2025 02:38

moonming approved these changes Jun 17, 2025

View reviewed changes

Baoyuantop merged commit cba5ba9 into apache:master Jun 17, 2025
7 checks passed

laz-xyr pushed a commit to laz-xyr/apisix that referenced this pull request Jun 19, 2025

docs: improve plugin-develop docs (apache#12242)

010aa5e

	Setup the `extra_lua_path` in `conf/config.yaml` to load your own code (or `extra_lua_cpath` for compiled .so or .dll file).
	Use the `extra_lua_path` parameter in `conf/config.yaml` file to load your custom plugin code (or use `extra_lua_cpath` for compiled `.so` or `.dll` file).

	The directory (`/path/to/example`) must contain the `/apisix/plugins` subdirectory.
	The directory (`/path/to/example`) must contain the `/apisix/plugins` subdirectory for L7 plugins.

	Once the plugins configuration is defined in `conf/config.yaml`, the new plugins list will replace the default configuration instead of merging. Therefore, when defining the `plugins` field, make sure to include the built-in plugins that are being used. To maintain consistency with the default behavior, you can include all the default enabled plugins defined in apisix/cli/config.lua.
	Once the plugins configuration is defined in `conf/config.yaml`, the new plugins list will replace the default configuration instead of merging. Therefore, when defining the `plugins` field, make sure to include the built-in plugins that are being used. To maintain consistency with the default behavior, you can include all the default enabled plugins defined in `apisix/cli/config.lua`.

	The [example-plugin](https://github.com/apache/apisix/blob/master/apisix/plugins/example-plugin.lua) plugin (local location: apisix/plugins/example-plugin.lua) provides an example.
	The [`example-plugin`](https://github.com/apache/apisix/blob/master/apisix/plugins/example-plugin.lua) plugin in this repo provides an example.


		## Check external dependencies

		If you have dependencies on external libraries, check the dependent items. if your plugin needs to use shared memory, it


		How to enable this feature?

		Enable `data_encryption` in `config.yaml`.

Uh oh!

Conversation

ctxinf commented May 22, 2025

Description

Which issue(s) this PR fixes:

Checklist

Uh oh!

kayx23 commented May 23, 2025

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

kayx23 left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants