Skip to content

v1.0
Compare
Choose a tag to compare
@yhnavein yhnavein released this 13 Jul 17:39
· 3 commits to master since this release
v1.0.0
4248695

🎉 v1.0 - OpenAPI 3 support! 🎉

Big release that introduces a lot of goodies and finally a OpenAPI 3 support. To make this happen in a fashionable manner we have dropped support for Swagger (or OpenAPI 2). Swagger is quite obsolete at this point, so everyone should migrate away anyway. Let's go through breaking changes and some of the mitigations.

⚠️ Breaking changes ⚠️

  • Dropped support for node < 18
  • Dropped support for Swagger (OpenAPI 2) specs
  • Query Parameters behave differently now
  • FormData works differently now
  • Some changes in templates - you need to review what changed in the templates to adjust yours accordingly (affects only those who are using custom templates)
  • parameter serialization is now different. Now it's much more robust, but it means that you might see a difference.
  • order of parameters may be different! Please double checks those operations that have body and other types of parameters involved

More context

OpenAPI 3

Because Swagger 2.0 specs are no longer supported, you need to decide how you want to deal with this:

  • (preferred) From your backend server generate OpenAPI 3.0 spec instead of version 2 (samples are updated to use OpenAPI 3.0)
  • Convert your OpenAPI 2.0 spec to 3.0 using swagger2openapi tool (or something similar)
  • If you can't do that for any reason, you can stick to Swaggie v0.x. But upgrade is suggested

OpenAPI 3 is a very good and wise choice - you get more features, better tools and a lot of issues fixed from previous spec version.

Query Paramerers

Before version 1.0 query parameters were handled in a very strange way - they were magically re-constructed from a flat list of parameters as more complex structure. And on top of this, serialization was done in a way that it works only in ASPNET. Not very customizable and not very flexible at all.

Thanks to OpenAPI 3 we were able to remove this big tech debt and replace it will built-in support for complex parameters. Only downside is that the backend-side tooling does not offer support for it out of the box, but it's quite easy to configure it manually. You can see examples of that in samples/dotnet/ directory.

With this new serialization mechanism of query params was introduced. New serialization code will be bundled in your app and it allows some level of configuration so most of the backend services should be handled correctly. If your app were using complex query params then it is a breaking change for you that you need to carefully address.

FormData

Sending files and providing form data to the backend now works slightly different.
Previously we were trying very hard to map some object type into a formData object, which was very nice for the developer, but it was also very error-prone and limiting. So right now when operation does require a formData object then just a FormData parameter will be exposed and developer can fill it up however he needs. It means that there is no type safety, but for now it's acceptable, as it makes file upload really easy as a result. We may come with a better solution in future when it feels a big problem.

Template changes

Because there were so many changes (app was basically rewritten) there are also some changes in the templates itself. If you were using custom templates then you need to take a look on the derived template and make adjusted changes in your custom one.

Other Changes

  • [Chore] Use undici instead of node-fetch
  • [Chore] Upgrade dependencies
  • [Chore] Multiple improvements to mocha tests and Wallaby.js configuration
  • [Tests] Add tests coverage with around 98%
Assets 2
Loading