swagger-editor icon indicating copy to clipboard operation
swagger-editor copied to clipboard

Published 20 hours ago • verified publisher icon swagger-api

Adding a "Refresh" menu alternative to refresh OpenAPI spec (PR candidate?)

Open tekeroth-snapcode opened this issue 2 years ago • 2 comments

I've been using the Swagger UI tool, but I was missing a "Refresh" button, to refresh the URL that once was used to fetch the OpenAPI spec. Instead, I had to go to "Import URL" and add the URL every time I made a change to the spec in the backend code.

I did try to see if a page refresh (F5) had any effect, but it didnt. So, I cloned the repo, and made some small changes for me to run locally. I was considering a PR for this, but I read this, and here is the issue first for ppl to comment on =)

Changes I made locally, that I can make into a PR if ppl want it:

  • Added a menu alternative "Refresh": image Pressing this button, will re-download the specification from a url previously entered
  • topbar.jsx: added the refreshURL function, that looks in window.localstorage for the 'url' and refreshes it if it is found. If there is no cached URL, it will call the importFromURL instead, opening up the popup to enter URL
  • topbar.jsx:: added code to importFromURL so that the URL is cached in window.localstorage
  • Modified the logic for Clear editor in function clearEditor to also remove the url from localStorage
  • added a toast library, since I was lacking feedback for some actions (like when doing an 'Import from URL'); https://www.cssscript.com/super-simple-javascript-message-toaster-toast-js/#google_vignette
  • added toasts for both Refresh and the Import from URL options image image image

I am not a web dev or react dev, so I was unsure where to place the toast lib js file. Currently, it is inside the /dist folder, so the index.html is modified like this:

  <link rel="stylesheet" href="./dist/ztoaster.min.css" />
</head>

<body>
  <div id="swagger-editor"></div>
  <script src="./dist/ztoaster.min.js"></script>

Please let me know if I should make a PR out of this, or not =)

tekeroth-snapcode avatar Jun 06 '22 08:06 tekeroth-snapcode

@tekeroth-snapcode Thanks for the idea and detailed description. The UX challenge I see is that "what" should be refreshed depends on the user and how they are using the tool at any given time. I think that if the scenario presented in the description is very common for you, it might be best to create your own plugin rather than as a general purpose update.

Regarding the minified toast code, if it's your own plugin, or your own local copy, then specifying the library in an html is fine. However, it's generally better to use an npm package (in package.json) as it is easier to maintain and keep updated.

All that said, if what you're looking for is to specify your own path to a definition, and you have access to your own swagger-editor instance (i.e. not editor.swagger.io), you can do so following this template:

In dev-helpers/index.html, add a url key like this:

const editor = SwaggerEditorBundle({
  dom_id: '#swagger-editor',
  url: "some-local-or-remote-path-to-definition.yaml" # define path here
  layout: 'StandaloneLayout',
  presets: [
    SwaggerEditorStandalonePreset
  ]
})

tim-lai avatar Jun 17 '22 22:06 tim-lai

Thanks for the input Tim.

"The UX challenge I see is that "what" should be refreshed depends on the user and how they are using the tool at any given time."

I don't really see the issue. I don't think that JS code can access a file to auto-update/refresh it, if they have chosen a file to view (security issue), but I am not mainly a web dev. An URL though, is more natural for me to "Refresh". So, I am not sure why it is a challenge. I can rename the menu alternative to "Refresh from URL"?

... if it's your own plugin

It is not. However, specifying packages for HTML coding is out of my comfort zone. I can do that writing C# applications, but not when I use Notepad++ to make some edits in this little thing =)

I still feel these updates are good, and if someone wants to NPM the toast lib, perhaps a PR can be created and someone can make that change before committing?

But, it is up to the community on this one =) I don't need this to be merged, as I have a local copy I am using =) So, I just thought that maybe this would be something ppl like, but if not, its fine too =)

Regards,

tekeroth-snapcode avatar Jun 18 '22 04:06 tekeroth-snapcode