paperclip-rs / paperclip

WIP OpenAPI tooling for Rust.
Apache License 2.0
896 stars 117 forks source link

Support transforming v3 spec to v2 in CLI #48

Open wafflespeanut opened 5 years ago

wafflespeanut commented 5 years ago

It would be nice to support transforming a v3 spec to v2 using the paperclip CLI. I think v2 and v3 only change in their structure, but if there's something more, then we can use vendor extensions to cover whatever we need.

pickfire commented 5 years ago

This would be a nice project to be done in https://github.com/pickfire/babelfish as well, maybe we could collaborate?

wafflespeanut commented 5 years ago

@pickfire I'd love to do that, but it looks like babelfish is a converter for encodings, whereas OpenAPI is a specification which could be in any encoding (JSON/YAML), so this is probably not in the scope of babelfish?

pickfire commented 5 years ago

Not really a converter for encodings, just a converter for stuff. Right now only encodings is there because encodings conversion is the easiest.

This is probably a good first non-encoding conversion.

wafflespeanut commented 5 years ago

... just a converter for stuff.

Isn't this ambiguous? Either way, it's probably time to update the scope of babelfish in its README and project description. 😄

Paperclip, on the other hand, is focusing entirely on tooling related to OpenAPI, which includes converting v3 to v2 and vice versa, which is why I believe it's well within the scope of this project.

wafflespeanut commented 5 years ago

One other thing I'd like to point out here is that the v2 and v3 spec aren't exactly interchangeable (v2 to v3 is straightforward, but the other way around isn't), so this also involves making a few decisions along the way, which may not be accepted by other OAPI tools because there's no universally accepted way to do that conversion.

pickfire commented 5 years ago

Isn't this ambiguous? Either way, it's probably time to update the scope of babelfish in its README and project description.

True, but I do like it being ambiguous rather than sprinkling around like how I see serde_*, even though some have very similar API (like serde_json and serde_cbor), it is not simple to just swap one with the other (like serde_yaml with serde_json).

So it might be good to have something for converting stuff, but at least try to get a similar API.

jayvdb commented 2 years ago

This would be a nice workaround for https://github.com/paperclip-rs/paperclip/issues/476

There are very few tools which can do this. c.f. https://stackoverflow.com/questions/56637299/convert-openapi-3-0-to-swagger-2-0

jayvdb commented 2 years ago

The transformations I needed to get my openapi 3 doc accepted by the v2 parser:

The result isnt perfect, but it is good enough for what I need atm .