Support transforming v3 spec to v2 in CLI

[wafflespeanut]

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]

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

[wafflespeanut]

@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]

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]

... 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]

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]

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]

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]

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

• Replace openapi: 3.x with swagger: 2.0
• Move components.schemas mapping to be top level definitions , and transform any $ref value in the same way, i.e. changing "#/components/schemas/ABC" to "#/definitions/ABC"

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