[Proposal]: Refactor route debug online

liuxiran commented 3 years ago

Please answer these questions before submitting your issue.

Why do you submit this issue?
[x] Feature or performance improvement refer to: https://github.com/apache/apisix-dashboard/issues/611 https://github.com/apache/apisix-dashboard/issues/469

Background

In the original implementation, we introduced real-swagger-ui as the basic tool for our debugging page, which relies on the OpenApi specification and is also a declared page.

However, API defined by Open API Specification pays more attention to parameter definition and return result definition, while Route in APISIX pays more attention to API forwarding capabilities. This distinction leads to the result that use the swagger ui to debug our route is inflexible and has a high data conversion cost, and it can not cover all cases. This is very similar to the situation where plugin now relies on real-jsonschema-form to generate visual forms.

So when we refactor this feature, we want to remove the real-swagger-ui lib, and implemented it in a light way.

How

Add a [Online Debug] button on route page, click button, get to the Online Debug page
the [Online Debug] page looks like below:

2020-11-20 16-02-21屏幕截图

The request is finally sent by the backend to APISIX

juzhiyuan commented 3 years ago

cc @LiteSun what do you think? 🤔

moonming commented 3 years ago

So do we implement debugging by ourselves?

juzhiyuan commented 3 years ago

Should we continue searching related OSS? If there doesn't have suitable OSS any more, we have to maintain one 🤔

Let's keep this proposal open for at least 72hours.

liuxiran commented 3 years ago

yes, I'm also looking for a suitable lib to implement this feature, If I find the suitable one, or we have a good recommendation, use lib is the preferred option :)

cc @juzhiyuan @moonming

moonming commented 3 years ago

how about postman？

liuxiran notifications@github.com于2020年11月20日周五下午8:42写道：

yes, I'm also looking for a suitable lib to implement this feature, If I find the suitable one, or we have a good recommendation, use lib is the preferred option :)

cc @juzhiyuan https://github.com/juzhiyuan @moonming https://github.com/moonming

— You are receiving this because you were mentioned.

Reply to this email directly, view it on GitHub https://github.com/apache/apisix-dashboard/issues/835#issuecomment-731148405, or unsubscribe https://github.com/notifications/unsubscribe-auth/AGJZBK4YMZIQGKLLEWDUVD3SQZP4DANCNFSM4T4OQVVA .

-- Thanks, Ming Wen Twitter: _WenMing

liuxiran commented 3 years ago

how about postman？

Postman is powerful and the user experience is very good, unfortunately, Its UI is not included in postman's many open source parts1.🤦‍♀️

There is an open source alternative for postman: postwoman, I simply experience its online demo environment2, which is similar to postman. Postwoman is a Vue wrote open source project3, and it has not been encapsulated as an out-of-the-box library. We can consider learning from its implementation, not convenient for direct use.

During the searching, I also looked through some simple online API debugging tools, I prefer one of them: sojson4, its page is refreshing and it is easy to operated. The disadvantage is that it can only test the APIs of the HTTP protocol, and there is no special treatment about authentication section. BTW, this is also not an OSS🤦‍♀️

Through this search, I also know that in addition to postman, there are many good API debugging and management tools, e.g: YApi, Eolinker and so on. This also got me thinking: do we need to provide users with a powerful API debugging tool, or just need to help users confirm that the api published on the APISIX can be used? IMHO, perhaps the latter is more demanding😊

Based on the above, my proposal is:

combine postwoman and sojson to implement a simple online debugging page in the dashboard. It does have a little bit of code, but they are all basic form operations, and the cost of maintenance is manageable.
support testing APIs of HTTP protocol first
as authentication is an important part of APIs, this part is also needed, and we can refer to postwoman's implementation

Just wait for others suggestion😊

Reference：

juzhiyuan commented 3 years ago

Just a note for new comers, Postwoman is now called hoppscotch and build with Nuxt.js (Vue.js).

juzhiyuan commented 3 years ago

combine postwoman and sojson to implement a simple online debugging page in the dashboard. It does have a little bit of code, but they are all basic form operations, and the cost of maintenance is manageable.

🤔 so we are going to implement this feature in the dashboard manually? It's ok for me, and a detailed dev plan would be better.

support testing APIs of HTTP protocol first

I'm not sure if it's extendable in the future and the only HTTP is enough currently, @moonming @membphis @tokers please have a check.

as authentication is an important part of APIs, this part is also needed, and we can refer to postwoman's implementation

👏

liuxiran commented 3 years ago

so we are going to implement this feature in the dashboard manually? It's ok for me, and a detailed dev plan would be better.

Based on the current research, I prefer to implement manually refer to hoppscotch. Later today, I will list a development plan :)

juzhiyuan commented 3 years ago

Got it 👏🏻

liuxiran commented 3 years ago

Update the page prototype

development plan

Support HTTP protocol first. Request processing reference: https://github.com/hoppscotch/hoppscotch/blob/95fe10b31262133810e2ee29a705fbfe757b4fc3/pages/index.vue#L1941
request params support: query params, body params, header params and authentications. Authentications reference: https://github.com/hoppscotch/hoppscotch/blob/95fe10b31262133810e2ee29a705fbfe757b4fc3/pages/index.vue auth related content
Use codemirror to do the display of response body
Refer to the UE of postman's parameter input to implement the input of request params.

PS: Other protocols supported by APISIX, such as websocket and gRPC, are needed for supplementary design. I prefer to open new issues to discuss and degin them after the http protocol completed😊, Considering adding tabs to extend the current debug page.

LiteSun commented 3 years ago

development plan

The development plan is ok for me 😊. please have a check. @juzhiyuan @moonming .

If there are no problems with the development plan, then we need to start the development task step by step to ensure that the feature is on schedule for completion at Milestone 2.2.
cc @liuxiran

liuxiran commented 3 years ago

If there are no problems with the development plan, then we need to start the development task step by step to ensure that the feature is on schedule for completion at Milestone 2.2. cc @liuxiran

got it, later this week I will open a pr about this feature 😊

liuxiran commented 3 years ago

all prs merged, close it now.

apache / apisix-dashboard