Swagger-ui: Usability improvement

[arthurdm]

Being used to the 2.x UI (ie: ibm.biz/restapi), to me it wasn't obvious that the "Try it out" button now enters into a development mode. I was expecting the "Try it out" button to actually execute a request, like it did in 2.x.

With 3.x, if I want to try out multiple endpoints I must click "Try it out" for each one, and then execute.

This issue is to suggest that we have a global toggle at the top of the UI that enters the "development mode", so that you can keep the default "documentation mode", but have an easier way to enter the development mode for all the endpoints. This would reduce the amount of buttons in your UI by 1 for every endpoint.

If we think about it, the "Authorize" button at the top means nothing if we're in documentation mode, since we won't be invoking any APIs.

So I suggest we replace the Authorize button with something like "Configure UI" (or similar) where the popup window/wizard would have a checkbox that said "Enable development mode", and when that checkbox was enabled then the authorization configuration inputs would show up and every endpoint would have the Try it out button, ie: execution.

This also creates a place where other configuration can go in the future from extenders of the UI - for example, if someone wants to hook up generators from the UI, filter tags, etc.

[webron]

@Minasokoni - we should discuss this.

[EricAtMSFT]

I agree with the "Authorize" button at the top being a strange user experience as @arthurdm mentioned.

Additionally, I think the current implementation fractures the actual API contract as defined in the swagger UI. For example, if my API accepts a header called "Authorize", that header is not shown in the list of editable parameters in the swagger UI.

Could we change it so that adding the Autihorize button data, it augments the param list down below and adds it so at least you can see it next to all the other params.

Thoughts?

[MartinX3]

I agree with the "Try it out" button.
I hate it.
Since I've got it, I need an additional click for every rest endpoint to execute data.
That's very annoying.

[offbeatful]

It will be ideal to have this configurable - like "ready to try it out".

[sparksterz]

I also found this to be rather frustrating. The other options I found online only would disable the button so swagger became a documentation source only - though if you'd like to use it as a developer and not have to click 'try it out' each time there didn't seem to be a great solution.

Here's what I came up with, it's a "wrong tool for the job" type of approach, but it at least kept our QA people happy during our swagger upgrade. Ideally we could tie this into the code base as an option:
```
var mutationObserver = new MutationObserver(function(mutations) {
mutations.forEach(function(mutation) {
document.querySelectorAll(".btn.try-out__btn:not(.cancel)").forEach(div => { div.click(); });
});
});

mutationObserver.observe(document.documentElement, {
attributes: true,
childList: true,
subtree: true
});

[johnyoonh]

@sparksterz As someone who uses django swagger, I am not too familiar with swagger-ui code base. Where did you add this code to make it work?

[sparksterz]

@sparksterz As someone who uses django swagger, I am not too familiar with swagger-ui code base. Where did you add this code to make it work?

Sorry, I was suggesting there's a better way to do this in the code base. My code is designed to run on the index.html that initializes the swagger-ui. I'm unfortunately not familiar with django, but if you can inject javascript to run after load somehow, that should work for you.

[Vaccano]

Here are a few more details on how to implement @sparksterz fantastic code:

1. Go to this page and make a copy of that file in your project called SwaggerIndex.html.

2. In the app.UseSwaggerUI configuration lambda (found in Startup.cs's Configure method), override the swagger index.html page by adding this:

   app.UseSwaggerUI(options =>
   {
   // ... Other code here as needed ...
   options.IndexStream = () => new FileStream($"{AppDomain.CurrentDomain.BaseDirectory}/SwaggerIndex.html", FileMode.Open);
   });

3. Open the properties of the SwaggerIndex.html file (found in the right click menu) and set the "Build Action" to _Content_ and the "Copy to Output Directory" to _Copy if Newer_

4. Add the following code near the bottom of the file, right before the line that reads window.ui = ui (which is the last line of the window.onload function):

   // Bypass the "Try it Out" button. https://github.com/swagger-api/swagger-ui/issues/2805
   var mutationObserver = new MutationObserver(function(mutations) {
   mutations.forEach(function(mutation) {
   document.querySelectorAll(".btn.try-out__btn:not(.cancel)").forEach(div => {
   div.click();
   div.style.display = "none";
   });
   });
   });

   mutationObserver.observe(document.documentElement, {
   attributes: true,
   childList: true,
   subtree: true
   });

Note, I added a div.style.display = "none"; to this code. It removes the "Try it Out" button completly. (Since this code does not allow it to be un-clicked, there is no point in displaying it.)