Support converting swagger (v2) spec to OpenAPI v3

[wafflespeanut]

This is useful for framework plugins which plan to use features from v3, in which case we'll use vendor extensions in v2 and convert it to v3.

[oli-cosmian]

So basically the steps as I see it are:

1. create v3 module with the appropriate serialization datastructures
2. add tests for v3 and test them with swagger
   • maybe there's a v3 test dataset somewhere that we can just pipe through to ensure we can deserialize and serialize everything?
3. Add From/Into impls to convert from v2 to v3 datastructures
4. Support transforming v3 spec to v2 in CLI #48 (same as 3, but the other direction)

[wafflespeanut]

That's correct. The structures and tests for (de-)serializing v3 spec should be easy enough, but the actual conversion may be complicated, so let's just focus on v2 to v3 in this issue, because that's what's needed for the plugin.

[Ploppz]

How does conversion from v2 to v3 help for e.g. #97, where the structure cannot even be represented in v2 (iirc)? Shouldn't we rather implement generating v3 directly to support issues like #97?

Edit: I see now that you plan to use "vendor extensions" to store the v3 data in v2 if I understood correctly.
However what about instead creating different "targets" of generation? What I mean is, keep the proc macros and the traits we currently have but make different modules v2 and v3 to generate different specs.
Sounds less complex to me, and most importantly it allows paperclip to maybe be used for generating e.g. RAML in the future by adding a new target raml. I don't know to what degree v2 and v3 differ and what overlap there is though.
Hope I make myself understood.

[Ploppz]

And comment @wafflespeanut ?

[wafflespeanut]

Sorry, somehow missed this.

What I mean is, keep the proc macros and the traits we currently have but make different modules v2 and v3 to generate different specs.

Paperclip codegen is written for v2. Having a separate v3 module will require significant changes in the codegen modules. Being an OpenAPI tooling library, v2 to v3 conversion (and vice versa) is something we should support anyway. So, I thought that we could just perform the conversions leveraging on vendor extensions (for idempotency) and reuse the codegen. For plugins, this would mean that they can stick to v2, and users can opt-in for v3 conversion if they wish to.

That said, paperclip will still have a v3 module in the future - only difference is that it will internally use v2 for generating code or spec, and from the user's perspective, it'd still work as expected.

e.g. RAML in the future by adding a new target raml

For now, I'm only focusing on OpenAPI. Maybe we could have this in the future versions once OpenAPI support is complete. 😅

I don't know to what degree v2 and v3 differ and what overlap there is though.

There isn't much. Few fields are renamed, some structural variations, and a bunch of features.

[timonbimon]

Hey I landed here after a long journey of moving from Python to Rust and then actix-web and then hunting for something that would help me go from code to OpenAPI specs. paperclip to the rescue 🤗. thanks!

After reading this thread I just wanted to point out that I think it is a mistake to focus too much on the old swagger/OpenAPi v2 spec. I am not an OpenAPI expert myself, but occasionally read some blog articles from Phil Sturgeon (the guy from https://apisyouwonthate.com/) and he seems to try to prevent people from "being stuck on old v2-based rubbish".

At least in the Python world I am happy to say that most people seem to have moved on from swagger to OpenAPI v3. Also here (https://openapi.tools/) is a list of OpenAPI tools that paperclip should definitely be on (as only the second tool written for Rust!).

[wafflespeanut]

OpenAPI v2 vs v3 is pretty much the Python 2 vs 3 problem - the only difference is that v2 hasn't reached EOL and people are still using it. I agree that we should focus more on v3 and I am planning to do that after 0.4.0 release. 😄

[timonbimon]

Yea the Python 2 vs 3 analogy is pretty spot on 😄

[Type1J]

I'm starting on a small and simple project that may grow to a larger more complicated project, and I want to add OpenAPI v3. My past efforts of doing that manually have been a bit painful, so I'm adding paperclip with OpenAPI v2 with faith that I'll have v3 in the future. Keep up the good work!

[Type1J]

I have a project coming up with a DSL with v3 only client code generator. Is v3 coming soon?

[polarathene]

Is v3 coming soon?

It does not look like it, track progress here.

Probably needs some help from others to contribute, if you're short on time perhaps you can contribute financially via a bounty to encourage others to help out?

[tiagolobocastro]

I've got a PR open to convert internal v2 spec to v3 => #311 (waiting review..)
@wafflespeanut has suggested before we keep paperclip's internal representation of the api as v2 and use extensions to specify the v3 specific features. So next step after that 311 would be to start adding the v3 specific sets as v2 extensions.