[Proposal]: Refactor route debug online

[liuxiran]

Please answer these questions before submitting your issue.

• Why do you submit this issue?
• Feature or performance improvement
  refer to:
  Proposal: Full lifecycle API management  #611
  Feature: debug a route online #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

1. Add a [Online Debug] button on route page, click button, get to the Online Debug page
   

2. the [Online Debug] page looks like below:

3. The request is finally sent by the backend to APISIX

[juzhiyuan]

cc @LiteSun what do you think? 🤔

[moonming]

So do we implement debugging by ourselves?

[juzhiyuan]

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]

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]

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 <#835 (comment)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/AGJZBK4YMZIQGKLLEWDUVD3SQZP4DANCNFSM4T4OQVVA> .

-- Thanks, Ming Wen Twitter: _WenMing

[liuxiran]

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 parts[1].🤦‍♀️

There is an open source alternative for postman: postwoman, I simply experience its online demo environment[2], which is similar to postman. Postwoman is a Vue wrote open source project[3], 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: sojson[4], 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：
[1]: https://github.com/postmanlabs
[2]:https://hoppscotch.io/?method=GET&url=https://httpbin.org&path=/get
[3]:https://github.com/luckyleihuan/Postwoman
[4]:https://www.sojson.com/http/test.html

[juzhiyuan]

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

[juzhiyuan]

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]

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]

Got it 👏🏻

[liuxiran]

Update the page prototype

---

development plan

1. Support HTTP protocol first. Request processing reference: https://github.com/hoppscotch/hoppscotch/blob/95fe10b31262133810e2ee29a705fbfe757b4fc3/pages/index.vue#L1941

2. 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

3. Use codemirror to do the display of response body

4. 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]

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]

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]

all prs merged, close it now.