Plans for dropping for OAS2 ?

[sergioisidoro]

Hi everyone,

Right now supporting OAS2 adds quite a big overhead, and I'm wondering if it really makes sense to continue supporting it. OAS 3.0.0 was released on 26 July 2017, and if we to continue to keep this gem in good shape, it's time to focus our resources into supporting OAS >= 3

Some examples of the overhead in keeping backwards compatibility include recent pull requests, like:

• Response examples - Fix examples, and upgrade examples to OAS3 #501
• Query - Support all possible query string style and format combinations #499

What do you think? Please react with 👎 if still need OAS2 support.

[lafferty151]

burn it out. It's difficult to maintain and it also leads to confusion as a user when trying to filter out the old conventions vs. the new.

[jtannas]

Agreed. We're a pretty small group maintaining this gem so supporting old versions saps energy better used elsewhere.
Maybe a v2.5.2 release with a deprecation notice for OAS2 support so we can start the ball rolling?

[jtannas]

Vaguely related... This seems like it'd be a major version change (ie. v3.0.0) due to it breaking lots of projects.
Skimming through the PRs I saw #396 which would also require a major version change.

Now that we have more maintainers on the project, should we let loose a bit and do a major refactor for v3?

[sergioisidoro]

This has been up for 15 days now. I'm not sure if there's any other way to reach people, but so far it seems there's no negative responses.

I think there's good points here about the refactoring / major release, but we need to be strategic with the amount of resources we have. A re-write, refactor would likely be too big of a bite, and it would likely end in failure. I'm more in favour of issuing a deprecation warning, and then gradually refactor things away from OAS2.

My biggest concern right now would be moving the metadata example object to a data structure closer to OAS3, and start go get rid of these upgrade methods:

rswag/rswag-specs/lib/rswag/specs/swagger_formatter.rb

Line 38 in 05e22c3

unless doc_version(swagger_doc).start_with?('2')

[jtannas]

Sorry, been away from computers for a few weeks but I can start helping out again now.

I think there's good points here about the refactoring / major release, but we need to be strategic with the amount of resources we have.

Good call. I'll focus on getting reviews done on existing PRs before starting any of my own work.

[romanblanco]

Starting this effort here: #574