Skip to content

Swagger-UI 3.0.0 Released!
Compare
Choose a tag to compare
@webron webron released this 29 Mar 22:10
· 4696 commits to master since this release
v3.0.0
373ea3c

Version 3.0 brings a complete rewrite of Swagger-UI in React.js 🎉

What's new?

This version is a rewrite of Swagger-UI from the the ground up. You get the features in previous versions with benefits:

  • Built using the latest technologies, based on React.js.
  • Faster than before, handling larger files.
  • Significantly easier to customize and extend.
  • Fresh UI, giving the classic look a modern twist.
  • Smaller overall size of the product.
  • This version will also make it easier for us to support the next versions of the spec. This version of Swagger-UI supports version 2 of the Swagger Spec/OAS. Support for older versions have been dropped.

Known Issues

As a fresh rewrite, some features did not make it in, notably:

  • Currently, the only configuration options available are the url and spec.
  • The JSON Form Editor is not implemented.
  • Shebang URL support for operations is missing.
  • Support for collectionFormat is partial.
  • l10n (translations) is not implemented.
  • Relative path support for external files is not implemented.

Interface changes

Swagger-UI is still called with a single configuration object, but...

  • the SwaggerUI function is no longer a constructor.
  • you no longer need to assign the result of calling SwaggerUI to a global variable
  • you no longer need to call the .load() method; UI will appear upon being called

To get started, take a look at how we're calling Swagger-UI in dist/index.html and customize the config object to your needs.

Configuration via query parameter is still present as well. For example, you can load the Petstore by opening dist/index.html?url=http://petstore.swagger.io/v2/swagger.json.

Distribution files & usage

Swagger-UI places four distribution files in its dist folder, along with a sourcemap (.map) for each file:

  • swagger-ui.js: Swagger-UI's core code without any dependencies.
  • swagger-ui.css: Swagger-UI's styling.
  • swagger-ui-bundle.js: Swagger-UI's core code, with all dependencies included.
  • swagger-ui-standalone-preset.js: A preset that provides the default StandaloneLayout for Swagger-UI. You'll want to include this unless you're creating your own layout file.

There's also an index.html file in the dist folder that can be opened directly, if you want to quickly get started with using Swagger-UI.

Developing

Run npm run dev to start a local dev server that will automatically hot reload any changes you make to Swagger-UI.

npm test is available as well: it will run Swagger-UI's tests and linter.

In order to persist your changes into the dist folder, npm run build must be run.

If you're modifying to suit your needs, we suggest writing a plugin and/or a custom layout instead of modifying the core code (see below!).

Prerequisites

  • Node 6.x
  • NPM 3.x

Extending

You can create your own plugins that:

  • provide custom pieces of state
  • wrap existing state actions
  • replace default components

You can also create your own layout that overrides the overall layout of components on the page.

Working with plugins and layouts will be easier if you're familiar with React. Most cases will be well-served by adding a plugin to src/plugins and including it in the standalone preset.

More advanced use cases can bring their own build pipeline for their plugins and layouts, and use Swagger-UI as a library- Swagger-Editor does this!

Assets 2
Loading