The New Swagger Editor and Swagger UI

Two years since the last update, and after listening to tens of thousands of user feedback, the new Swagger UI and Swagger Editor are finally here!  They bring speed and reliability to the forefront of the API design and documentation process. The new versions also introduce extensibility mechanisms that allow users to fully customize the interface and build their own functionality on top of the core Swagger platform. 

You can find the projects in their respective GitHub repositories.

Swagger-UI: https://github.com/swagger-api/swagger-ui

Swagger-Editor: https://github.com/swagger-api/swagger-editor

Obviously we expect questions, so we've added an FAQ section below.

FAQ

Wait, what just happened?

Swagger-UI was first released in 2011, and Swagger-Editor was in 2014. As most of you are aware, those two projects were developed independently, were based on different technologies and did not provide the same user experience. We ended up 'merging' the two projects using a similar technology base for both. As part of our work, we've completely reworked swagger-js as well.

So there's one project now?

Well, no. We've created a new pluggable system. Swagger-UI now contains the core of that system, and the editor is simply a set of plugins added to it. We still provide you a way to run swagger-editor as a project without having to understand how these plugins work.

Why go through all the trouble?

Quite a few reasons:

  • As mentioned above, merging of technologies and moving to newer ones. The projects became old and it was time to get up to speed.
  • We wanted to provide a familiar UI for both projects.
  • To give you more customizablity. A lot more.
  • To give you more extensibility. You guessed it, a lot more.
  • To make it easier for us to support the next version of the spec.
  • To improve performance of rendering, validation.
  • To improve validations in the editor, making it easier for users to write specs from scratch.

Hey, what happened to the UI?! I liked it much better in Swagger-X!

We took the the best of the existing projects, freshened things up and voila! We're likely to make more changes in the upcoming weeks, and definitely more when we support the next version of the spec.

But I want the old look'n'feel!

That's the great thing about the new projects - if you want to modify the UI to suit your needs that's a lot easier now.

Does it support the next version of the spec?

As mentioned above, one of the main reasons for this change is to make it easier for us to support the next version of the spec. That's the next main thing on our to-do list.

What about issues in the previous versions of the projects? Will the be developed further? How long can we expect support?

Given the next version of the spec, and the work we've put into the new projects, we're no long actively developing the previous versions. Our efforts are focused on the new version of the projects. We'll continue supporting the older version for a few more months to give everyone enough time for the transition. We'll publish an official announcement regarding officially dropping support. We would still provide new releases of the old projects in some cases, depending on how critical the issues are.

What spec versions are supported by the new projects?

2.0 and we're working on support for the next version of the spec. Older versions are no longer supported. For those of you who still use version older than 2.0 of the spec, we encourage to take the time and look into upgrading it.

It's missing feature X! Feature Y is broken!

Oops. We've tried to get as close as possible to feature parity, but we're likely to have missed a few. Help us out by filing the missing feature as a ticket on the project.

How can I help?

Just as you did before:

  • Something doesn't work? File a ticket!
  • Something is missing? File a ticket!
  • You'd like to see even more? File a ticket!
  • Got time to resolve any of the above? Submit a PR!

It's that simple.