Update to OpenAPI 3.0

[sarpera]

Current DRS schema definition is based on OpenAPI (fka swagger) 2.0. Shall we update it to conform to OpenAPI 3.0 (the latest version of the OpenAPI Specification)?

Immediate benefit of the update is to have new data model capabilities which would make the ongoing efforts on creating PRs a bliss.

[ddietterich]

I agree. It would be good to use 3.0.

The only downside I know is that swagger-codegen does not yet support 3.0. Anyone planning to use that tool?

[denis-yuen]

We do, but we've had successful experiments with swagger-codegen 3.0.4 https://github.com/swagger-api/swagger-codegen/releases/tag/v3.0.4 which does support OpenAPi 3.0.

[geoffjentry]

To echo - the conventional wisdom in the cloud workstream has been what @ddietterich stated, but is obviously going to be a moving target. My $0.02 is that as long as the infrastructural challenges are surmountable that we should go the 3.0 route

[briandoconnor]

What impact will this have on build? If this update just works then lets go for it. If not, then we might delay this for v0.1

[jaeddy]

Just noticed that swagger2markup (which we use to autogen documentation during the build process) doesn't currently support OpenAPI 3 — there might be some potential workarounds we could try:
Swagger2Markup/swagger2markup#340

I think we'd need to adjust the Swagger UI HTML template as well, but that should be a quick fix.