Skip to content

Swagger-Editor 3.0.0 Released!
Compare
Choose a tag to compare
@webron webron released this 29 Mar 22:15
· 2485 commits to master since this release
v3.0.0
58796ec

Swagger-Editor

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

You should check out the Swagger-UI 3.0 release notes as well. Swagger-Editor 3 is structured as a plugin to Swagger-UI 3, so seeing what's new upstream will help understand what's going on with Swagger-Editor.

What's new?

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

  • Built using the latest technologies, based on React.js.
  • Swagger-Editor is now an extension to Swagger-UI.
  • Faster than before, handling larger files.
  • Significantly easier to customize and extend.
  • Unified UI, with the new Swagger-UI project.
  • 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-Editor supports version 2 of the Swagger Spec/OAS. Support for older versions have been dropped.
  • Improved validation, customized validation errors, to make spec authoring easier.
  • Improved auto-suggest, works both for keys and values, contextually.

Known Issues

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

  • Everything listed in Swagger-UI's Known Issues.
  • The integration with the codegen is still missing.
  • Importing specs from a URL is not implemented.
  • Many of the configuration options are not yet available.

Interface changes

Only the dom_id configuration option is supported at this time.

index.html still persists in the root of the project. Opening it directly is the quickest way to get started with Swagger-Editor!

Relationship with Swagger-UI

Swagger-Editor 3 uses Swagger-UI as a library, adding editor functionality through a set of plugins that are provided to Swagger-UI. We also provide a default layout (EditorLayout) for displaying the Editor and UI alongside each other.

Distribution files & usage

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

  • swagger-editor.js: Code for the Editor without any dependencies included
  • swagger-editor.css: Styling for the editor
  • swagger-editor-bundle.js: Code for the editor with all dependencies included
  • validation.worker.js: An external worker file for the validation engine. You won't need this unless you're trying to get validation working in a very old browser.

Developing

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

If you'd like to develop Swagger-UI inside Swagger-Editor, you can npm link your local Swagger-UI to Swagger-Editor.

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

See Swagger-UI's section on Extending for more information.

Assets 2
Loading