[GitHub] [apisix-dashboard] liuxiran commented on issue #1039: Build plugin form according to its jsonschema
liuxiran commented on issue #1039: URL: https://github.com/apache/apisix-dashboard/issues/1039#issuecomment-785629052 > @liuxiran > Thanks for the explanation. > Maintaining a separate template is troublesome, and after the plugin schema is updated in APISIX, it may be easier to miss here and cannot keep up with the update of the plugin schema. Thanks @nic-chen, and your concern is really a problem indeed. We originally envisioned automatically generating templates through schema, and we got a scheme to generate template stochasticly, but it can not support to generate template refer to the usage scenario. It's not very friendly for plugin with options. It would be better to find a way to generate template reder to the different usage scenario, let me try to find it. 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. For queries about this service, please contact Infrastructure at: us...@infra.apache.org
[GitHub] [apisix-dashboard] liuxiran commented on issue #1039: Build plugin form according to its jsonschema
liuxiran commented on issue #1039: URL: https://github.com/apache/apisix-dashboard/issues/1039#issuecomment-783550440 > I have a little doubt, where does the configuration template come from? And how do we maintain them. Thanks. @liuxiran The configuration template plans to define manually in a new dir e.g: `plugin_templates` in dashboard repo, and we have to maintain them when the configuration rules of the plugin changed. The template would contain three parts: 1. `usage scenario`, which means if users want to use plugin in scenarioA, the can refer scenarioA's template to complete their configuration. Just take `limit-count` for example:  `cluster-level precision traffic limit` is one of the scenarios for `limit-count` plugin. we want to extract the common usage scenarios indicated in the document to generate different `template`. For some plugins only have one usage scenario, then we would support something called `Universal configuration` template for them. Maybe there are no specific usage scenarios labeled in the document for some plugins, then we have to add them for better use. 2. `description of the parameters`, which means add comments for every config item, user can config the plugin refer the comments instead of opening the doc page. 3. `default value of the parameters`, which means the recommended config(or recommended config policy) for the config item in the target usage scenario 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. For queries about this service, please contact Infrastructure at: us...@infra.apache.org
[GitHub] [apisix-dashboard] liuxiran commented on issue #1039: Build plugin form according to its jsonschema
liuxiran commented on issue #1039: URL: https://github.com/apache/apisix-dashboard/issues/1039#issuecomment-782746152 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. For queries about this service, please contact Infrastructure at: us...@infra.apache.org
[GitHub] [apisix-dashboard] liuxiran commented on issue #1039: Build plugin form according to its jsonschema
liuxiran commented on issue #1039: URL: https://github.com/apache/apisix-dashboard/issues/1039#issuecomment-771504973 I talked about this issue with @juzhiyuan offline and we have reached the following consensus: 1. To improve the user experience, we would add plugin configuration templates, which are a range of configurations based on the different use scenario, in the templates, we should add instructions for each configuration item at the same time. **where would these configuration template stored?** Stored in files would be better. Create a template file for each plugin under something called `doc/plugin_templates` dir in dashboard **what is the template file type?** The type of the template file can be `markdown` or `yaml`. `yaml` would be easier to parse **what would the template look like?** This needs further discussion. may be we can use follows: take limit-conn for an example ```yaml scenario1: # limit concurrency per client's IP conn: 1 # the maximum number of concurrent requests allowed burst: 0 # the number of excessive concurrent requests (or connections) allowed to be delayed default_conn_delay: 0.1 # the default processing latency of a typical connection rejected_code: 503 # returned when the request exceeds conn + burst will be rejected, default is 503 key: "remote_addr" # limit the concurrency level scenario2: # limit concurrency per server's IP conn: 1 # the maximum number of concurrent requests allowed burst: 0 # the number of excessive concurrent requests (or connections) allowed to be delayed default_conn_delay: 0.1 # the default processing latency of a typical connection rejected_code: 503 # returned when the request exceeds conn + burst will be rejected, default is 503 key: "server_addr" # limit the concurrency level ... ``` 2. To support instructions in the configuration templates, we should use `yaml` instead of `json` in dashboard plugin codemirror. 3. in the plugin config page, we would add a select box to select configuration template, and show the template configuration in the codemirror:  Welcome any suggestions to improve the program cc @imjoey @LiteSun @membphis 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. For queries about this service, please contact Infrastructure at: us...@infra.apache.org
[GitHub] [apisix-dashboard] liuxiran commented on issue #1039: Build plugin form according to its jsonschema
liuxiran commented on issue #1039: URL: https://github.com/apache/apisix-dashboard/issues/1039#issuecomment-771504973 I talked about this issue with @juzhiyuan offline and we have reached the following consensus: 1. To improve the user experience, we would add plugin configuration templates, which are a range of configurations based on the different use scenario, in the templates, we should add instructions for each configuration item at the same time. **where would these configuration template stored?** Stored in files would be better. Create a template file for each plugin under something called `doc/plugin_templates` dir in dashboard **what is the template file type?** The type of the template file can be `markdown` or `yaml`. `yaml` would be easier to parse **what would the template look like?** This needs further discussion. may be we can use follows: take limit-conn for an example ```yaml scenario1: # limit concurrency per client's IP conn: 1 # the maximum number of concurrent requests allowed burst: 0 # the number of excessive concurrent requests (or connections) allowed to be delayed default_conn_delay: 0.1 # the default processing latency of a typical connection rejected_code: 503 # returned when the request exceeds conn + burst will be rejected, default is 503 key: "remote_addr" # limit the concurrency level scenario2: # limit concurrency per server's IP conn: 1 # the maximum number of concurrent requests allowed burst: 0 # the number of excessive concurrent requests (or connections) allowed to be delayed default_conn_delay: 0.1 # the default processing latency of a typical connection rejected_code: 503 # returned when the request exceeds conn + burst will be rejected, default is 503 key: "server_addr" # limit the concurrency level ... ``` 2. To support instructions in the configuration templates, we should use `yaml` instead of `json` in dashboard plugin codemirror. 3. in the plugin config page, we would add a select box to select configuration template, and show the template configuration in the codemirror:  Welcome any suggestions to improve the program cc @imjoey @LiteSun @membphis 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. For queries about this service, please contact Infrastructure at: us...@infra.apache.org
[GitHub] [apisix-dashboard] liuxiran commented on issue #1039: Build plugin form according to its jsonschema
liuxiran commented on issue #1039:
URL:
https://github.com/apache/apisix-dashboard/issues/1039#issuecomment-770432807
While researching this issue, I found a very cool library:
`json-schema-faker`[1], an OSS with a large number of references and stars,
used to generate fake data according to its `jsonshema`. I tested some of our
plugins' schema, no matter which draft the schema is, the fake data can cover
well.
### What the fake data looks like
Take `api-breaker` for an example:
* Jsonschema for api-breaker:
https://github.com/apache/apisix/blob/09a4673a98269cb204c12a66980ff2f6f54abf39/apisix/plugins/api-breaker.lua#L30
* the fake data generated by `json-schema-faker`: (configurable)
```json
{
"break_response_code": 200,
"healthy": {
"http_statuses": [200],
"successes": 3
},
"max_breaker_sec": 300,
"unhealthy": {
"failures": 3,
"http_statuses": [500]
},
"disable": false
}
```
### How to add comments
The fake data generated by `json-schema-faker` will be the `template` of the
plugins. When enable a plugin, we could show this template instead of empty
fields.
If we want to add comments for the `template`, we have to use `yaml` instead
of `json`.
It's such a coincidence that there is an issue[2] in `json-schema-faker`
accurately matches our needs, I tried the method provided by the author, it
worked very well
* add comments for api-breaker: **please pay attention to `title` and
`deacription` fields**
```json
{
"title": "plugin: api-breaker",
"description": "some information about api-breaker",
"$comment": "this is a mark for our injected plugin schema",
"properties": {
...
"break_response_code": {
"title": "break_response_code title",
"maximum": 599,
"minimum": 200,
"type": "integer",
"description": "comment for break_response_code"
},
"healthy": {
"default": {
"http_statuses": [200],
"successes": 3
},
"properties": {
"http_statuses": {
"default": [200],
"items": {
"maximum": 499,
"minimum": 200,
"type": "integer"
},
"minItems": 1,
"type": "array",
"uniqueItems": true,
"description": "comment for
http_statuses"
},
"successes": {
"default": 3,
"minimum": 1,
"type": "integer",
"description": "comment for successes"
}
},
"type": "object"
},
},
"required": ["break_response_code"],
"type": "object"
}
```
**the yaml data with comments**
```yaml
## plugin: api-breaker
#
# some information about api-breaker
## break_response_code title ##
#
# comment for break_response_code
#
# Minimum value: 200
#
# Maximum value: 599
#
break_response_code: 200
## healthy ##
#
# Default value: [object Object]
#
healthy:
## http_statuses ##
#
# comment for http_statuses
#
# Default value: 200
#
http_statuses:
- 200
## successes ##
#
# comment for successes
#
# Default value: 3
#
# Minimum value: 1
#
successes: 3
## max_breaker_sec ##
#
# comment for max_breaker_sec
#
# Default value: 300
#
# Minimum value: 3
#
max_breaker_sec: 300
## unhealthy ##
#
# Default value: [object Object]
#
unhealthy:
## failures ##
#
# comment for unhealthy failures
#
# Default value: 3
#
# Minimum value: 1
#
failures: 3
## http_statuses ##
#
# comment for unhealthy http_statuses
#
# Default value: 500
#
http_statuses:
- 500
## disable ##
#
# comment for disable
#
disable: false
```
### What we planed to do
1. Import `json-schema-faker` to generate
[GitHub] [apisix-dashboard] liuxiran commented on issue #1039: Build plugin form according to its jsonschema
liuxiran commented on issue #1039: URL: https://github.com/apache/apisix-dashboard/issues/1039#issuecomment-766983789 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. For queries about this service, please contact Infrastructure at: us...@infra.apache.org
[GitHub] [apisix-dashboard] liuxiran commented on issue #1039: Build plugin form according to its jsonschema
liuxiran commented on issue #1039: URL: https://github.com/apache/apisix-dashboard/issues/1039#issuecomment-767241353 > Could we store those templates in a JSON or YAML file in Dashboard repo haha? These templates would be better to be a part of part of the APISIX plugin document, and dashboards obtained by synchronizing data(if possible) 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. For queries about this service, please contact Infrastructure at: us...@infra.apache.org
[GitHub] [apisix-dashboard] liuxiran commented on issue #1039: Build plugin form according to its jsonschema
liuxiran commented on issue #1039: URL: https://github.com/apache/apisix-dashboard/issues/1039#issuecomment-767237468 > @juzhiyuan @liuxiran > > yep, inspired by Aliyun API gateway, we could support both configuration template and UI form for users. Let us get this done to improve the plugin experience. ok, I'll look into what `configuration template` involves, and then split them into points to discuss and confirm one by one. 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. For queries about this service, please contact Infrastructure at: us...@infra.apache.org
[GitHub] [apisix-dashboard] liuxiran commented on issue #1039: Build plugin form according to its jsonschema
liuxiran commented on issue #1039: URL: https://github.com/apache/apisix-dashboard/issues/1039#issuecomment-766983789 > Maybe we could use `form-render`[1] to build UI first, then export JSON schema, and update the plugin's schema finally? > > [1] https://x-render.gitee.io/schema-generator/playground > > cc @liuxiran @imjoey What a cool component library~! Recently, during my approach to #1241 , I rethought this issue: 1. build plugin form: (I'm ready to give up this plan) A: customized plugin form: Instead of build form from its Jsonschema, a customized plugin form can tell user what each item is and how to fill it better, but it comes with high maintenance costs just take `proxy-rewrite` for example  B: build form from its jsonschema: someone like `request-validation` which need to define the schema, could not be build correctly, even if we have already found this cool library. Besides, we need to ask for a more friendly definition of plugin schema in APISIX(e.g: define description for each field item) 1. continue to optimize our codemirror: In fact, users only need to know intuitively what configuration items the plugin has what the meaning of each config item and how to configure them, no matter the plugin is build with a form or a codemirror config. The biggest advantage of direct configuration is full coverage of plugin function, we only need to improve its user experience. I've experienced the config of plugin in Aliyun API Gateway, which also use directly config, I think there are a few things we can refer to:  A: Several configuration templates are available, this is very helpful for most users, it will save the cost of study. B: Each configuration item is described in detail, it tells user how to configure directly C: The help document is shown in a modal, this makes it easier for users to copy and paste configuration items cc @juzhiyuan 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. For queries about this service, please contact Infrastructure at: us...@infra.apache.org
