Re: [PR] docs: improve `plugin-develop` docs [apisix]
Baoyuantop merged PR #12242: URL: https://github.com/apache/apisix/pull/12242 -- This is an automated message from the Apache Git Service. To respond to the message, please log on to GitHub and use the URL above to go to the specific comment. To unsubscribe, e-mail: [email protected] For queries about this service, please contact Infrastructure at: [email protected]
Re: [PR] docs: improve `plugin-develop` docs [apisix]
slow-groovin commented on code in PR #12242:
URL: https://github.com/apache/apisix/pull/12242#discussion_r2134579294
##
docs/en/latest/plugin-develop.md:
##
@@ -228,55 +159,28 @@ local metadata_schema = {
required = {"ikey", "skey"},
}
-local plugin_name = "example-plugin"
-
-local _M = {
-version = 0.1,
-priority = 0,-- TODO: add a type field, may be a good idea
-name = plugin_name,
-schema = schema,
-metadata_schema = metadata_schema,
-}
-```
-
-You might have noticed the key-auth plugin has `type = 'auth'` in its
definition.
-When we set the type of plugin to `auth`, it means that this plugin is an
authentication plugin.
-
-An authentication plugin needs to choose a consumer after execution. For
example, in key-auth plugin, it calls the `consumer.attach_consumer` to attach
a consumer, which is chosen via the `apikey` header.
-
-To interact with the `consumer` resource, this type of plugin needs to provide
a `consumer_schema` to check the `plugins` configuration in the `consumer`.
-
-Here is the consumer configuration for key-auth plugin:
-
-```json
-{
- "username": "Joe",
- "plugins": {
-"key-auth": {
- "key": "Joe's key"
-}
- }
-}
+function _M.check_schema(conf, schema_type)
+--- check schema for metadata
+if schema_type == core.schema.TYPE_METADATA then
+return core.schema.check(metadata_schema, conf)
+end
+return core.schema.check(schema, conf)
+end
```
-It will be used when you try to create a [Consumer](./admin-api.md#consumer)
-
-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
Review Comment:
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](https://apisix.apache.org/search/?q=L4), I thought it's better that the
maintainers provide detailed content for this part.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: [email protected]
For queries about this service, please contact Infrastructure at:
[email protected]
Re: [PR] docs: improve `plugin-develop` docs [apisix]
kayx23 commented on code in PR #12242:
URL: https://github.com/apache/apisix/pull/12242#discussion_r2131850270
##
docs/en/latest/plugin-develop.md:
##
@@ -228,55 +159,28 @@ local metadata_schema = {
required = {"ikey", "skey"},
}
-local plugin_name = "example-plugin"
-
-local _M = {
-version = 0.1,
-priority = 0,-- TODO: add a type field, may be a good idea
-name = plugin_name,
-schema = schema,
-metadata_schema = metadata_schema,
-}
-```
-
-You might have noticed the key-auth plugin has `type = 'auth'` in its
definition.
-When we set the type of plugin to `auth`, it means that this plugin is an
authentication plugin.
-
-An authentication plugin needs to choose a consumer after execution. For
example, in key-auth plugin, it calls the `consumer.attach_consumer` to attach
a consumer, which is chosen via the `apikey` header.
-
-To interact with the `consumer` resource, this type of plugin needs to provide
a `consumer_schema` to check the `plugins` configuration in the `consumer`.
-
-Here is the consumer configuration for key-auth plugin:
-
-```json
-{
- "username": "Joe",
- "plugins": {
-"key-auth": {
- "key": "Joe's key"
-}
- }
-}
+function _M.check_schema(conf, schema_type)
+--- check schema for metadata
+if schema_type == core.schema.TYPE_METADATA then
+return core.schema.check(metadata_schema, conf)
+end
+return core.schema.check(schema, conf)
+end
```
-It will be used when you try to create a [Consumer](./admin-api.md#consumer)
-
-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
Review Comment:
Can put the title like this:
```suggestion
```lua title="key-auth.lua"
```
and remove the comment in the code block:
https://github.com/user-attachments/assets/5fffe4dc-c693-4cfb-8a7d-87b7abf4bed1";
/>
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: [email protected]
For queries about this service, please contact Infrastructure at:
[email protected]
Re: [PR] docs: improve `plugin-develop` docs [apisix]
slow-groovin commented on code in PR #12242:
URL: https://github.com/apache/apisix/pull/12242#discussion_r2123237839
##
docs/en/latest/plugin-develop.md:
##
@@ -205,18 +129,25 @@ local schema = {
The schema defines a non-negative number `i`, a string `s`, a non-empty array
of `t`, and `ip` / `port`. Only `i` is required.
-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, schema_type)__
method to complete the specification verification.
```lua
function _M.check_schema(conf, schema_type)
+if schema_type == core.schema.TYPE_METADATA then
+return core.schema.check(metadata_schema, conf)
+end
return core.schema.check(schema, conf)
end
```
+:::note
+
Note: the project has provided the public method "__core.schema.check__",
which can be used directly to complete JSON
verification.
-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.
Review Comment:
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.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: [email protected]
For queries about this service, please contact Infrastructure at:
[email protected]
Re: [PR] docs: improve `plugin-develop` docs [apisix]
kayx23 commented on code in PR #12242:
URL: https://github.com/apache/apisix/pull/12242#discussion_r2122635738
##
docs/en/latest/plugin-develop.md:
##
@@ -205,18 +129,25 @@ local schema = {
The schema defines a non-negative number `i`, a string `s`, a non-empty array
of `t`, and `ip` / `port`. Only `i` is required.
-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, schema_type)__
method to complete the specification verification.
```lua
function _M.check_schema(conf, schema_type)
+if schema_type == core.schema.TYPE_METADATA then
+return core.schema.check(metadata_schema, conf)
+end
return core.schema.check(schema, conf)
end
```
+:::note
+
Note: the project has provided the public method "__core.schema.check__",
which can be used directly to complete JSON
verification.
-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.
Review Comment:
A couple issues regarding this rearrangement:
1. it is easier to read if this info is moved down to its corresponding
content:
https://github.com/user-attachments/assets/5e5ec305-2ca8-4cda-bf59-281af20ea9f2";
/>
2. Missing information - `consumer_schema` was removed in this PR. Why?
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: [email protected]
For queries about this service, please contact Infrastructure at:
[email protected]
Re: [PR] docs: improve `plugin-develop` docs [apisix]
slow-groovin commented on code in PR #12242: URL: https://github.com/apache/apisix/pull/12242#discussion_r2110886795 ## docs/en/latest/plugin-develop.md: ## @@ -24,84 +24,58 @@ title: Plugin Develop This documentation is about developing plugin in Lua. For other languages, see [external plugin](./external-plugin.md). -## where to put your plugins +## 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). -1. modify the source of APISIX and redistribute it (not so recommended) -1. setup the `extra_lua_path` and `extra_lua_cpath` in `conf/config.yaml` to load your own code. Your own code will be loaded instead of the builtin one with the same name, so you can use this way to override the builtin behavior if needed. +For example, you can create a directory `/path/to/example`: -For example, you can create a directory structure like this: +```yaml +apisix: +... +extra_lua_path: "/path/to/example/?.lua" +``` + +The structure of the `example` directory should look like this: ``` ├── example -│ └── apisix -│ ├── plugins -│ │ └── 3rd-party.lua -│ └── stream Review Comment: I know nothing about the stream folder, please revise this section yourself. -- This is an automated message from the Apache Git Service. To respond to the message, please log on to GitHub and use the URL above to go to the specific comment. To unsubscribe, e-mail: [email protected] For queries about this service, please contact Infrastructure at: [email protected]
Re: [PR] docs: improve `plugin-develop` docs [apisix]
kayx23 commented on code in PR #12242: URL: https://github.com/apache/apisix/pull/12242#discussion_r2108618051 ## docs/en/latest/plugin-develop.md: ## @@ -24,84 +24,58 @@ title: Plugin Develop This documentation is about developing plugin in Lua. For other languages, see [external plugin](./external-plugin.md). -## where to put your plugins +## 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). Review Comment: ```suggestion 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). ``` ## docs/en/latest/plugin-develop.md: ## @@ -24,84 +24,58 @@ title: Plugin Develop This documentation is about developing plugin in Lua. For other languages, see [external plugin](./external-plugin.md). -## where to put your plugins +## 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). -1. modify the source of APISIX and redistribute it (not so recommended) -1. setup the `extra_lua_path` and `extra_lua_cpath` in `conf/config.yaml` to load your own code. Your own code will be loaded instead of the builtin one with the same name, so you can use this way to override the builtin behavior if needed. +For example, you can create a directory `/path/to/example`: -For example, you can create a directory structure like this: +```yaml +apisix: +... +extra_lua_path: "/path/to/example/?.lua" +``` + +The structure of the `example` directory should look like this: ``` ├── example -│ └── apisix -│ ├── plugins -│ │ └── 3rd-party.lua -│ └── stream -│ └── plugins -│ └── 3rd-party.lua +│ └── apisix +│ └── plugins +│ └── 3rd-party.lua ``` :::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. ::: -Then add this configuration into your `conf/config.yaml`: +## Enable the plugin -```yaml -apisix: -... -extra_lua_path: "/path/to/example/?.lua" -``` - -Now using `require "apisix.plugins.3rd-party"` will load your plugin, just like `require "apisix.plugins.jwt-auth"` will load the `jwt-auth` plugin. - -Sometimes you may want to override a method instead of a whole file. In this case, you can configure `lua_module_hook` in `conf/config.yaml` -to introduce your hook. - -Assumed your configuration is: +To enable your custom plugin, add the plugin list to `conf/config.yaml` and append your plugin name. For instance: ```yaml -apisix: -... -extra_lua_path: "/path/to/example/?.lua" -lua_module_hook: "my_hook" +plugins: # See `conf/config.yaml.example` for an example + - ... # Add existing plugins + - your-plugin # Add your custom plugin name (name is the plugin name defined in the code) ``` -The `example/my_hook.lua` will be loaded when APISIX starts, and you can use this hook to replace a method in APISIX. -The example of [my_hook.lua](https://github.com/apache/apisix/blob/master/example/my_hook.lua) can be found under the `example` directory of this project. +:::warning -## check dependencies +In particular, most APISIX plugins are enabled by default when the plugins field configuration is not defined (The default enabled plugins can be found in [apisix/cli/config.lua](https://github.com/apache/apisix/blob/master/apisix/cli/config.lua)). -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**. Review Comment: ```suggestion 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`. ``` ## docs/en/latest/plugin-develop.md: ## @@ -437,7 +246,119 @@ function _M.access(conf, ctx) e
Re: [PR] docs: improve `plugin-develop` docs [apisix]
kayx23 commented on PR #12242: URL: https://github.com/apache/apisix/pull/12242#issuecomment-2903754411 Please resolve lint errors. -- This is an automated message from the Apache Git Service. To respond to the message, please log on to GitHub and use the URL above to go to the specific comment. To unsubscribe, e-mail: [email protected] For queries about this service, please contact Infrastructure at: [email protected]
[PR] docs: improve `plugin-develop` docs [apisix]
slow-groovin opened a new pull request, #12242:
URL: https://github.com/apache/apisix/pull/12242
### Description
I encountered some difficulties while following the plugin-develop
documentation during development:
1. The structure of the document was confusing and not clearly organized; it
didn’t progress from basic to advanced concepts.
2. Some critical parts were not explained.
https://github.com/apache/apisix/issues/11835#issuecomment-2545125455
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
- [x] I have explained the need for this PR and the problem it solves
- [x] 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](https://github.com/apache/apisix/tree/master#community) first)
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: [email protected]
For queries about this service, please contact Infrastructure at:
[email protected]
