Update the Web API Swagger 2.0 specification to OpenAPI 3.0

[MattiSG]

The Web API specification is currently described in the Swagger 2.0 format, which has been improved upon significantly in OpenAPI 3.0.

There is no known immediate use case for this update, but we should expect maintenance to be made easier, and the tooling ecosystem to move towards the more recent standard.

As a reuser, please use this issue to mention your interest in this update if your integration would be made easier with it 🙂

[MattiSG]

As an author of the spec, I can tell it would be very useful to be able to use oneOf as a consequence of #982, which is not supported in Swagger 2.0 as specified in OAI/OpenAPI-Specification#333.

[MattiSG]

This would also enable spec-compliant reuse of headers, which are currently defined under commons and is not valid.

[bonjourmauko]

Thanks @MattiSG ! I think this a much waited change, and maybe also a fix for openfisca/legislation-explorer#227 ✨

[bonjourmauko]

Hello @MattiSG , has this been fixed by #989?

[MattiSG]

Yes!