It's been a very long time since we posted about what's going on with Swagger, but it's not too late to give you some updates! Over the last few months, we've worked on making quite a few changes, some are more technical, and some are more user-facing. In this post, we'll try to cover some of these updates, in no order of importance.
General Releases
We've made numerous releases for various of our projects, and it probably doesn't make sense to go through all of them. However, in case you didn't know, all of our releases come with release notes that detail improvements, bug fixes, and (as much as we try to avoid them) breaking changes.
Every project in GitHub, has a 'Releases' section, for example: https://github.com/swagger-api/swagger-ui/releases.
There you can find all our notes and various versions. Another good way to keep track of new releases is to 'watch' a project, and set it to 'Releases only'. That way, you'll only get notifications when releases are made, without all the issues and PRs that are being submitted to it.
Notable Releases
Even though we release versions on a regular basis, we've also recently published some releases that offer new functionality. All the new projects are also now based on OpenAPI 3.0!
We've officially released version 2 of the Validator Badge. While we changed the infrastructure of the project, the API has remained the same, with the added bonus that it now supports OpenAPI 3.0 on top of Swagger/OpenAPI 2.0.
To reflect the change, the master branch of the project represents the current version, whereas branch v1 has a copy of the previous version.
Hosted version update: Up until today, the hosted version existed under https://online.swagger.io/validator. For now, this URL is still active and exposes v1 of the Validator. The new version of the validator is hosted under https://validator.swagger.io and the latest versions of Swagger UI use that URL. We highly encourage those of you who use the old URL to switch to the new one. At some point in the future, we'll either redirect the old URL to the new one, or shut it down.
Reporting issues and submitting contributions: The Validator Badge project is a simple web service project encapsulating Swagger Parser. If you have issues with the web service (for example, the API is not working as you'd expect), please file issues at https://github.com/swagger-api/validator-badge. However, if you find issues with the validation itself, please file them at https://github.com/swagger-api/swagger-parser. If you're unsure, fear not - file the issue where you'd like and we will transfer it if needed.
The Converter is a new-ish project. We've had it behind the scenes for a while now, and we're finally releasing it as open source. Much like the Validator Badge, Swagger Converter is a web service wrapping Swagger Parser, providing the ability to convert older definition files to OpenAPI 3. The hosted version is live at https://converter.swagger.io and you can also either build and run it yourself, or use the docker image.
Reporting issues and submitting contributions: If you have issues with the web service (for example, the API is not working as you'd expect), please file issues at https://github.com/swagger-api/swagger-converter. However, if you find issues with the conversion itself, please file them at https://github.com/swagger-api/swagger-parser. Again, if you're unsure, just file the issue where you'd like and we'll transfer it if needed.
Wait, what?! It's been a long time coming, but the OpenAPI 3 version of the pet store is now live!
At the moment, you can find it at https://petstore3.swagger.io. In the future, we will replace the main https://petstore.swagger.io with v3 and keep v2 alive in a separate URL.
Pet Store v3 currently is just a simple migration of v2 to OpenAPI 3. However, right now, we don't take full advantage of the OAS3 features. We do want to change this, and you can help too!
Unlike previous versions of the pet store, that used the code-first approach, in the new version of the pet store we're utilizing the design-first approach. This means that even if you're not familiar with the code itself, as long as you know OpenAPI 3, you can submit PRs and help us improve the pet store itself. Just remember that the pet store is not necessarily intended to show a good API design but more so cover the different features of the spec.
Another change is that the source code of the pet store is now easier to find. Just hop over to https://github.com/swagger-api/swagger-petstore. Both hosted versions are there (master branch for v3, v2 branch for v2).
Reporting issues and submitting contributions: Now with the new repository, submitting ideas, fixes, changes is easier than ever. Simply go to https://github.com/swagger-api/swagger-petstore to get started. If you want to just make suggestions to the API exposed, simply submit PRs against https://github.com/swagger-api/swagger-petstore/blob/master/src/main/resources/openapi.yaml, the wonders of the design-first approach.
New Contribution Guide
One of the great advantages of open source projects is the ability to contribute and improve them based on your own needs. Whether you're a newcomer or an experienced user, you may have some questions about the best way to contribute.
We value your time, and appreciate the willingness to help. Here is some information to help you get started. Remember, open source contributions come in many forms and not just code contributions.
In our Contribution Guide, we describe different ways to help, from answering questions, to testing, and making code changes.
For those of you who are not aware, when you open a new issue in GitHub, there's going to be a link (or more) at the bottom of the right side-panel, pointing to common resources provided by the project maintainers. For example:
You can find the source of the Contribution Guide here: https://github.com/swagger-api/.github/blob/master/CONTRIBUTING.md.
As always, we welcome feedback and contributions, just remember that this is the general guide for all our projects.