Swagger-UI 3.0.0 Released!

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!

Swagger-UI 2.2.8 Released!

Small fix to address scopes and some JSON processing issues.

Fixes:

• incorrectly converting content to blobs #2528
• Pass only correct scopes #2524 #2514
• Ignore facebook garble in OAuth URL
• Minified better with gulp sourcemap

Swagger-UI 2.2.7 Released!

Just in time for the holidays! An update to Swagger-UI, primarily focused on image downloading and rendering. Note! There are some limitations in Internet Explorer (all versions) for image downloading. Please follow #2525 for updates if this is giving you headaches. Heck, you can even contribute a fix!

Fixes:

• application/octet-stream not downloading correctly #1605, #2427
• Images may not be rendered correctly #2512
• Example values overwritten #2520

Swagger-UI 2.2.6 Released!

If it 'aint fixed, broke it!

Minor fixes to address a couple regressions in v2.2.2-v2.2.5. Namely:

• Japanese messages updated #2437
• Chinese messages updated #2449
• Font src attribute fixed #2429
• File attachment blob download fixed #2439

From the swagger-js 2.1.23 update:

• Scheme selection broken for https swagger-api/swagger-js#871
• Fixed superagent send for multipart/form-data sending swagger-api/swagger-js#879
• Added support for custom http clients swagger-api/swagger-js#875
• Full vendor extensions now available in swagger-ui for customization swagger-api/swagger-js#869

Swagger-UI 2.2.5 Released!

Update to address a bug in swagger-js where schemes are sometimes not honored.

Swagger-UI 2.2.4 Released!

Fixed an issue where query parameters without default values were being shown as undefined.

Swagger-UI 2.2.3 Released!

Minor update to Swagger-UI that brings better handling of XSS vulnerabilities using the excellent sanitize-html project.

Swagger-UI 2.2.2 Released!

Small fix to address overly-aggressive escaping of model signatures #2350.

While at it...

• Added composer.json file #2347
• Added Catalan translation #2351

Please see detailed release notes here!

Swagger-UI 2.2.1 Released!

A new version of swagger-ui has been released, and contains major functionality enhancements as well as a ton of performance fixes. Oh, we fixed some bugs, too.

Upgrade notes!

Please note! There are updates in the parent index.html which are required for using 2.2.1. Please compare the included libraries from your container with those in the swagger-ui distribution!

New features

• Integrated authentication! Now your basic auth, apiKey, OAuth 2.0 Implicit security definitions are automatically rendered in the UI #1923, #1922, #1889
• Updated Handlebars! Now using Handlebars 4.0.0 #2306
• Highlight pack updated #2235
• Security fixes prevent XSS injections #1866, #1865, #1864, #1863, #1617, #1154, #830

Enhancements

• Speed improvements with large spec files, references #2292, #2198
• Better checking for invalid specs #2258
• File upload improvements #2251
• Updated curl file upload command #2178
• Added filename in download headers #1991
• More translations #2066
• OAuth redirect_url added #2056
• Latest swagger-js #2244, #2223
• :port removed from curl sample #2236

Bug Fixes

• Fixed issue with $ref and external files #2304
• Content-Type header sometimes not sent in request #2242
• Arrays of primitives in formData now correctly sent
• Authorize bugs: cancel button (#2238), logout button #2193,
• OPTIONS javascript issue resolved #2207
• XML rendering issues #2191, #2167, #2077, #2067, #1982, #1931, #1918, #1901
• Boolean parameters causing rendering issues #2190
• OAuth scopes #2150
• IE issues #2144, #2063, #2002
• Basic auth now works with no password(?) #2114
• Curl makes funny characters #2113, #1978
• Auth sends headers corectly #2075
• Gulp tasks updated #2227
• Some cases have wrong produces/consumes headers #2042
• Title not used as model name by default #2029
• Rendering fails with missing supportedSubmitMethods #1949
• Rendering nested refs #1943, #1859
• Enum values not displayed in response class #1907
• Open external docs in new tab/window #1899

Please share your feedback, issues, chocolates as you see fit.

Swagger-ui 2.1.4 has been released!

A new version of swagger-ui has been released, and contains fixes, enhancements, and unicorns.

Enhancements

• Updated swagger-client to 2.1.10, allowing better support for references, composition, rendering of complex models
• Added translation files for French, Italian, Japanese, Polish, Russian, Turkish (#1631, #1717, #1725, #1843, #1844, #1559). Also more translation elements (#1521)
• A JSON editor has been added to make it easier to edit and supply JSON payloads (#1589)
• Better OAuth support (#1648)
• Client credentials flow (#1825)
• LESS refactoring makes it much easier to edit style (#1756)

Deprecations

• Please note that rendering in the swagger-js client will be removed in 2.2.x releases (see #1248). These methods will be removed, and are being logged to console in the mean time.