Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Default page served isn't configurable and lacks search / listAll functionality #1122

Closed
porcoesphino opened this issue Jan 6, 2016 · 4 comments
Labels
Milestone

Comments

@porcoesphino
Copy link

As a new user, exploration of a API is faster if the user can search for endpoints or expand all (not fully, just to list).

The swagger-ui.html file is not configurable in anyway so adding this would requires serving your own copy of the file. Some options that should be accessible are docExpansion, javascript at the end of the page or a div for some custom html.

The default swagger-ui.html should include a button to expand all to list view. Here is a javascript bookmarklet doing this:

javascript:(function(){
  if (window.swaggerUi.getOption('docExpansion') === 'list') {
    window.swaggerUi.collapseAll();
    window.swaggerUi.setOption('docExpansion', 'none');
  } else {
    window.swaggerUi.listAll();
    window.swaggerUi.setOption('docExpansion', 'list');
  }
})();

The default swagger-ui.html should include a searchbox of the api. Here is a bookmarklet using the API key box to do this (taken from this swagger-ui bug):

javascript:(function(){

    var checkEmptyResources = function() {
        return $('.resource').each(function(i, res) {
          var visibleChildren;
          visibleChildren = $(res).find('.operation').filter(function(ii, op) {
            return $(op).css('display') !== 'none';
          });
          if (visibleChildren.size() <= 0) {
            return $(res).hide();
          } else {
            return $(res).show();
          }
        });
    };

    var pattern, searchterm;
    searchterm = $('#input_apiKey').val();
    pattern = new RegExp(searchterm, 'i');
    $('.operation').each(function(i, op) {
      var opDescription, opID, opSummary;
      opID = $(op).prop('id');
      opSummary = $(op).find('a.toggleOperation').text();
      opDescription = $(op).find('.markdown p').text();
      if ((pattern.test(opID)) || (pattern.test(opSummary)) || (pattern.test(opDescription))) {
        return $(op).show();
      } else {
        return $(op).hide();
      }
    });
    return checkEmptyResources();
})();

Noted that swagger-ui are working on adjusting their javascript library to add this but that doesn't change:

  • the ease of changing swagger-ui.html for someone who would rather be working on something else,
  • this being a trivial change to a default file that users can't configure in this repository that will have value to most users of the final served page.
@dilipkrish
Copy link
Member

These are great ideas 🤘. Would love to get a PR since you're more familiar with this than I admit to being.

Having said that, the swagger-ui that ships with this library is more of a convenience for spring framework users rather than a full blown customized swagger-ui. The fewer customizations to the script the better we stand at taking upgrades from the mother ship.

@dilipkrish dilipkrish added this to the 2.4.0 milestone Jan 6, 2016
@porcoesphino
Copy link
Author

Oh yeah, it would only be an alterations to swagger-ui.html. I'll work on an PR for you.

@dilipkrish
Copy link
Member

also have a look at this pr

@porcoesphino
Copy link
Author

Thank you.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
Projects
None yet
Development

No branches or pull requests

2 participants