Ponelat

SwaggerUI's plugin system

Don't know what swagger-ui is or does? Check it out.

What is it trying to do?

The plugin system was designed so that developers can change little pieces of swagger-ui without forking the whole project.

How was that approached?

The plugins provide pieces (eg: actions,selectors,components,...) that can be extended by replacing or decorating those pieces.
The simplest case is replacing a component, with your own.

For example, I'd like to change the "Try It Out" button's text to read, "Just do it".

Slightly largish example to follow...

// Create a plugin (NOTE: this code would need to be compiled because of the JSX syntax)
const myPlugin = {
  components: {
    TryItOutButton: () => {
      // NOTE: We're not handling the click event for brevity.
      return (
        <div className="try-out">
          <button className="btn try-out__btn">Just do it!</button>
        </div>
      )
    }
  }
}

// ....
const ui = SwaggerUIBundle({
  // ... required fields left out for brevity
  // ... see https://github.com/swagger-api/swagger-ui#swaggeruibundle 
  plugins: [ ..., myPlugin ],
})

What was that?

We did two things there, we made a simple plugin, that'll replace the TryItOutButton component, with our own. Then we passed that plugin into swagger-ui constructor.
The TryItOutButton component was defined by another plugin, likely from the default preset(s). Since our plugin is the last ( order matters ), we override the original button.
We're simply merging in our mini-systems ( plugins ) into one large system. Its really just a fancier way of doing.. Object.assign({}, plugin1, plugin2, ...etc)

In fact, that's how the system is built, we just merge all the plugins together. We added some magic to it, so that we get some cool things like:

  • Replacing an action while still being able to call the original.
  • Putting actions/selectors/reducers under namespaces, which don't share state.
... which probably sounds like Gibberish, until we explain the system a little more.

So those docs you spoke of?

They're a work in progress :)
I could use your help though...
Take a look at the open Documentation issues in GitHub and comment, either ask for clarity on certain topics or propose new ones


...Thanks for making OSS great! And happy API'ing!