Switching to OpenAPI 3.0

[m-mohr]

Do we want to switch to OpenAPI 3.0? OpenAPI 2.0 is a limited in defining several data types (e.g. ArgSet due to missing oneOf, anyOf, ...) and doesn't support OAuth natively, for example.

I think the only reason to stick with OpenAPI 2.0 was the availability of the code generation tools. The question is: Is anybody after POC using one of the generators not available?

WWU is not using them. Is @aljacob still using it? But Java is supported in release candidate state for OpenAPI 3.0 anyway AFAIK. What about the others?

[m-mohr]

This issue in Swagger UI is blocking: swagger-api/swagger-ui#3437
Many examples are useless in the docs without having this solved.
The following PR may fix this: swagger-api/swagger-ui#4092

Regarding code generation there is one opinion so far from @aljacob

Since we now have a solid base for the API from what we did in 0.0.2, for me the switch is fine and I think we can live for the near future without a code generation tool.
However on the long run, it would be nice to have something again, so that it becomes easier for other people to implement their drivers for back-ends not yet foreseen in the current project. Hopefully the tools around the swagger world until then have caught up with the development and are available...

That's exactly what I thought, too. ;)

[m-mohr]

An alternative to Swagger UI for API spec doc generation could be ReDoc: https://github.com/Rebilly/ReDoc

[m-mohr]

Changed to OpenAPI 3.0 in 0.3 branch.

[m-mohr]

Fixed the example issues in SwaggerUI by moving the examples from the outer examples-attribute to the schema example-attribute. Could still be a good idea to move to ReDoc for their multi-example support for programming languages. We could serve examples for all client libraries.