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](https://github.com/swagger-api/swagger-editor) does this!