The Swagger Team is proud to announce the first release candidates of both swagger-core and swagger-parser, adding support for the OpenAPI Specification 3.0.0 (OAS 3.0)!
As the new version of the specification is released, we’re certain users are anxious to try it out. Previously, we’ve published support for OAS 3.0 in both Swagger UI and Swagger Editor, and now it’s time for the Java world to take that step.
The release of the new libraries is intended for early adopters, and there are a few known limitations which are outlined below. With this first release we are looking for your help in filing issues and even submitting PRs with fixes. Be aware that as release candidates, the API may change until the final release, introducing breaking changes to your application.
Here’s what’s new in Swagger-core and Swagger-parser:
Swagger-core is a set of modules that enables integration with a few Java technologies, such as JAX-RS and Servlets, to produce OpenAPI definitions. However, swagger-core is more than that – it also provides a set of models to represent an API definition in the OpenAPI standard, and a set of annotations that can be used to decorate code with additional information. Both modules are used by other projects under the Swagger toolset and by community tools.
The new version of swagger-core represents a major rewrite of code, and is currently numbered 2.0.0-rc1. This version provides a few key features and changes:
- Supports OAS3 only. Just like previous swagger-core versions, only one specification version is supported.
- As a first major version release in a while – the annotations were completely rewritten and adjusted to support the new version of the spec.
- This means that swagger-core 2.X is a breaking change from previous versions.
- The current RC supports only JAX-RS2.
- The codebase uses Java 8.
We encourage you to read the full release notes and get more information. The code itself can be found in the 2.0 branch and will remain there until an official stable release. We’ll also start providing more documentation in the wiki regarding the new integration in the upcoming weeks.
Swagger-parser, our OpenAPI definition deserializer, has also been released with the version 2.0.0-rc0. Much like swagger-core, this provides you support on reading OAS3 definitions and parsing them into a model tree. The project also includes a converter from OAS2 to OAS3 and will use it automatically when trying to parse such definitions. Like swagger-core, the code itself can be found in the 2.0 branch and will remain there until an official stable release.
What’s next for the other Swagger Java projects?
Glad you asked! We’re currently focused on expanding swagger-core, improving the converter in swagger-parser, and implementing a new version of swagger-inflector with OAS3 support.
The validator-badge and swagger-codegen will be next!
For the latest updates on what’s being released by the Swagger Team, you can follow us on Twitter @SwaggerAPI or subscribe in the blog sidebar.