Example support for requests

[codeasashu]

Is your feature request related to a problem? Please describe.
I want to add examples for requests (just like they have in postman) to showcase the expected responses, when sharing with a team. This gives a place to share, modify and improve the responses a lot. This is usually the case when APIs are being discussed and designed, before the actual development.

This will also help generate expected openapi response definitions (using oneOf) from the pool of examples I have for a request.

Describe the solution you'd like
Request can have an additional tab, called "examples" where I can input:

• expected response HTTP status code (eg. 200)
• expected response content type
• expected response body (using the code editor) as raw text

It should allow me to add as many examples as I can add. For each status codes, I can have multiple examples (which is highly unusual when json schema differs, but why not).

Describe alternatives you've considered
I've been relying on json schema to convert responses to their json schema, adding them to openapi as schemas and referencing them to responses manually.

Additional context
I've prepared a pull request, which allows me to do so. Although, the UI is not appealing, yet it showcases a basic working prototype. Since I've add examples as a attribute to the request object, it happens to get synced automatically, without breaking anything.

List of examples

Adding example

[nijikokun]

Hi @codeasashu,

Thank you for raising this and also the implementation PR.

I'm wondering if the Unit Testing functionality from Designer would solve the same issues (which takes it a step further and allows you to execute and confirm the status code as well). They look similar in use-case and solve the same expectations.

As a note, you don't need a specification to try out Unit Testing in Designer. It is based off the requests that you make in the debug tab, so this should allow you to try it out and formulate an opinion.

[nijikokun]

After discussion internally, wondering if this could tie into unit tests, and thoughts from others on this.

Being able to create or store examples (maybe not the best terminology here) that you can reference from a unit test to be executed with (body, headers, etc).

Another item we discussed was the potential for this to be a plugin, there are some challenges here, we lack the APIs necessary to do this just now and need to refine the UI capabilities within plugins but it would make a good use-case for doing so.

[codeasashu]

I initially started this off as a plugin, but then it only allowed me to use Modals to contain the json.
The current implementation also uses Modals, since I am not aware of how can I add a new sub-window in the request UI for each example. (I am very new to react and electron).

AFAIK, with plugins, I can:

• Add modals
• Add context menu for each request to trigger open this modal
• Use store to save the example

However, I wish to see the list of all request examples as well. This would mean three sections:

Section 1: Shows the list of all the examples for given request
Section 2: Shows "Add example" page
Section 3: Shows "Edit example" page

To implement the above 3, I can either use a single modal with tabs (not very intuitive and difficult to implement), or I can use another modal (on top of existing modal) to show the add/edit forms. I am not a huge fan of modals already. Hence, this PR addresses this using a new tab in request panel.

Maybe, if plugin can add a new tab (instead of modal) per request, it would save a lot of trouble and I don't see any reason to change the native code any bit.

[codeasashu]

My usecase for examples is more for the sharing (and discussing) than for the unit testing. This means some part of audiences like Project managers, group of team leads etc. who might get an idea about the feature, by seeing the API response.

Adding, editing examples is quite intuitive too. I usually use postman example editor, during the team meetings, to share how I think the API might look good. Changing examples, pre-discussing the response schema, etc. gives a very narrative experience, and that seems to be a good thing.

I do not know if referencing examples from unit tests can solve this. I will check and see if that solves my usecase.

[develohpanda]

We have recently explored UI plugins - see the implementation here. If this was a candidate to be a plugin there would be several APIs we would need to explore and expose. I quite like this use case, but agree that it might fit better as a plugin.

I do not know if referencing examples from unit tests can solve this. I will check and see if that solves my usecase.

This is more of an idea to consume some of the examples, to set the unit test body (less duplication), but I feel like that would be supplementary behavior to examples for how you want to use them.

[codeasashu]

@develohpanda As commented above, I can use modals (which I am limited to, when using as a plugin), but then I will be "forced" to open yet another modal on top of existing to allow add/editing the examples.

Can you help me with how I can do the same within same modal? I am not against using modals, however, Opening another modal within a modal means implementing the whole modal class, I guess

[develohpanda]

I don't think it's a great idea to open multiple modals on top of each other.

I can use modals ( which I am limited to, when using as a plugin)

We can likely add plugin API to allow you to create a tab and control the content inside it, and you can already control the content inside a modal as per this. That should, in theory, allow you to achieve the design that you have linked in the description above.

Hmm - the code-editor may prove to be tricky, though. 😢

Then comes a separate question of data persistence for a plugin, whether it needs to be synced (TBC, but currently plugin data is not a part of any sync or export).

If this is useful then we can explore adding some APIs. 😄

[codeasashu]

@develohpanda Thanks for pointing me to the right direction.

I can still use the code-editor I used (by making a copy of it inside the plugin) or can add mine, inside the component. I will try to add another PR which allows adding a tab to a request editor. Then everything I've made in this PR can be added as a plugin.

Code-editor inside modal is tricky, yes. However, if given a certain height for the code-editor, I think it can render pretty well.

[develohpanda]

That sounds good. From an interface standpoint, it would be nice to define the tabs via a requestTabs array exported from the plugin, similar to how the documentActions and workspaceActions one works.

Feel free to reach out to me on Slack if you need any assistance, and/or create draft PRs for early reviews, so you don't end up working too deep on an approach and have to then rework. 😄

[codeasashu]

@develohpanda I've added a draft PR for review. Will add tests if everything looks good

[stale[bot]]

This issue has been automatically marked as stale because it has not had recent activity. It will be closed if no further activity occurs. Thank you for your contributions.