Display curl cli command before execution
nneul opened this issue · comments
Currently in the generated UI, there does not appear to be any way to view and verify the exact request that is going to be submitted (or to SEE the request to copy and run somewhere else) without clicking "Execute" which immediately invokes the request. It would be much safer and more functional if the UI would "show the invocation" and a separate click to actually invoke it.
A nice way to display this would be to just have the curl display full time (or even better a "Invocation" section, with future capability to submit additional 'formatters' similar to what Elements supports)
Seams reasonable to have this displayed, we would definitely accept a PR to display the curl even before execution.
I will call out though:
It would be much safer and more functional if the UI would "show the invocation" and a separate click to actually invoke it.
What does safer and more functional mean for you here?
And
(or even better a "Invocation" section, with future capability to submit additional 'formatters' similar to what Elements supports)
Isn't clear for us what this means either. Can you explain more about what an Invocation section would mean and what use case formatters would have for you? I.e. what problem do you see that this would help with.
The current expected implementation would be to show the curl in place exactly where it is now, however it sounds like you have some ideas about this could be even better. So before we start accepting PRs to support, would you be able to add some clarity for the use cases you are thinking about related to the above questions?
In any case, thanks for the suggestion!
- Warren
Sure, so for my testing scenario, there are two problem situations:
- I can use the displayed API docs anywhere, but invoking them requires additional context/specific IPs/whichever.
- I have an API where the different doc presenters (rapidoc, swagger, elements, openapi-explorer) are not all consistent in how they handle certain parameter types. In particular, something simple like array parameters - which are completely broken in elements. As a result, I really want to be able to see the api request that is going to be invoked, before I actually tell it to invoke it. (That's the safer) aspect.
For example, I saw one case where when the api doc wasn't quite correct that it was going to send it as 'param=value1,value2' instead of 'param=value1¶m=value2'. I'd like a chance to see that I'm asking it to "create entity named 'value1,value2' instead of asking to create two entities. In the current openapi-explorer - me even clicking over to "Execute" immediately invokes the request, fails, and THEN I'm given the opportunity to see "Oh, yeah, I have the syntax all wrong."
I really LIKE the way elements does it - but it's just got some really bad breakage in it's UI otherwise, which openapi-explorer does not.
For the "formatters" part of the suggestion, here's what I see on elements:
I don't particularly care for their layout/overall appearance of that section/page spacing/etc -- but what I do like is that I can see immediately in various forms (curl, python, etc.) how to do the invocation, in addition to just being able to "submit request" -- including being able to look at a 'raw http/1.1' request if so desired.
Not suggesting that you need to implement all of those 'formatters', but if the tool had framework for it and perhaps showed two cases out of the box - curl and http, that would be easy submissions/contributions that others could do. (I know for example I'd submit one in a language that I use that no one else ever seems to include in the samples/api docs/etc.)
As far as appearance/how you could build this - consider just "REQUEST SAMPLE" - have that be a box just above RESPONSE - initially filled with the request that would be generated from whatever defaults are populated. Update that live as parameters are changed in the REQUEST section.
For the second part, that REQUEST SAMPLE could include tabs or dropdown or similar to look at different possible implementations/tools/etc.
You can absolutely already specify x-code-options to list all the custom implementations you want in the languages you would like to display. I think this could help a lot with getting your visibility into your users hands: x-code-samples.
However that doesn't necessary fix the problem. I will ask that while continuing to discuss this issue, please avoid the following things:
- solutioning - talking about solutions without first discussing the problem
- comparing this project to other alternatives
We don't have any experience with "Elements" or understand how they call things, so it is really confusing to talk about "formatters". It helps a lot to share the problem as plain and simply as possible.
If you had asked something like:
I would like to display different code examples for different languages
Then I would have immediately known to share with you the code samples documentation.
Again, there are lots of things that we can do, but we can't implement any of them without better understanding the problem. So can we please talk about the problem specifically?
From what little I can gather, it sounds like you are saying:
As one of my users, I would like to know how to correct construct a
curlcommand. However, when I go to your API Explorer, it isn't listed anywhere. I have to click execute just to find out what my curl command should look like.
Is that correct?
In that language, I would rephrase as:
As one of my users, I would like to see examples of correctly constructing a
curlcommand orpython(or other language) script to invoke this API request. However, when I go to the API explorer, it isn't listed anywhere. I have to click on execute just to find out what a curl command should look like.I do not want to invoke the API, I want to view how to invoke it with a given set of inputs.
Awesome, thank you!
This feature has been added in #176 Release 1.1, You can check it out in the new release and see if it matches your expectations. If anything doesn't work as you would expect just let us know and we can work to improve it.
Looks like it's working beautifully for GET requests, but not updating for POST forms. It does update the Full Request content when you execute though.
Hmm, that could be possible, Want to take a look to see if something can be added, I assume something like an @change or @input event is missing from those.
@nneul this has been updated in a new release. If you find additional issues would you be able to open a new issue with a minimal example and quick description of the field which doesn't work? Thanks!
@wparad Wow, what timing. I actually had that on my list to try to take a look at updating today. 👍
I took a look, and it is VERY close, there is still one difference between it and the query args in terms of behavior though - on the query args page, as you type each letter, the curl content updates. On the FORM based entry, it does not update until you click somewhere or switch/tab/etc. to a new field.
That's entirely minor though and this does address my primary need. I fiddled around a bit with trying to edit this, but it's outside of my very limited level of nodejs knowledge.
As far as test case, this should be enough to demonstrate. It DOES appear to work with live updates on your demo site with the json request body. If you need a full api.yml example, let me know and I can put one together.
requestBody:
content:
application/x-www-form-urlencoded:
schema:
type: object
properties:
user:
required:
- user
Awesome, I've updated some of the events from @change to @input where possible. @input events in html should fire on every character input, while @change is only supposed to fire "at the end". See the new version solves those as well, or if there are still additional places missing. Cheers.
@wparad Working perfectly!