OpenAPI generation by openapi-gen

[petrkotas]

What is the issue observed

The current OpenAPI generation is tightly coupled with written generation code. The complication with the current implementation is the hard written rules combining the generation to the code itself.

Such mechanism complicates extending the API with x-ms-extensions like in the PR: #930. The PR had to hard code exceptions for desired fields, that want to use x-ms-enum.

Proposed solution

Generating the API in a similar way that Kubernetes generates its API: https://github.com/kubernetes/kube-openapi
enables describing the types via annotations directly near the type definitions, it also enables the API extensions, the same way as Kubernetes extended the types e.g. https://github.com/kubernetes/kube-openapi/blob/master/pkg/aggregator/aggregator.go#L30

Finaly launching the API server and exporting the API makes the resulting JSON with paths and operations. Generating API directly from the API server eliminates the need for maintaining path in multiple places.

Drawbacks

One huge drawback is the work required to implement such a generation mechanism. The https://github.com/kubernetes/gengo base library is well maintained and a good start; the https://github.com/kubernetes/kube-openapi can be forked and use as a template for the change.

However, it is a major rewrite and a long term goal.

The benefit from the long term is a more straightforward opanAPI generation not tightly coupled with the code generation code. Moreover, when done properly, the code can be used to generate API for more Azure projects based on Golang.