Use OpenAPI V3 for documentation generation

[Jefftree]

OpenAPI V3 has been GA for a couple of releases and it would be great if we could generate documentation based on OpenAPI V3 instead of V2. kubectl-validate has samples of how to fetch the OpenAPI V3 schemas from the k/k repo. https://github.com/kubernetes-sigs/kubectl-validate/tree/main/pkg/openapiclient

The benefit is that V3 schemas are more rich, include additional information like field defaults, field nullable, oneof, etc.

[sftim]

We shouldn't label this using the Kubernetes definition of help wanted, even if we do welcome help.

See https://www.kubernetes.dev/docs/guide/help-wanted/

[tengqm]

There doesn't seem a stable package for parsing OpenAPI v3. The go-openapi project explicitly states that it doesn't support v3. The specv3 subproject has not been updated for many years.

If we take a step back and see what are the benefits v3 brings to us, we can see little. The V3 spec complicates the parsing of an API spec, it introduces more ambiguity (yes, I'm talking about "oneOf", "anyOf") for code generators. If there ARE some benefits that I'm unaware of, please let us know. Maybe it worth develop a new parser for OpenAPI v3, who knows? However, at this stage, OpenAPI v3 doesn't worth this effort.

[Jefftree]

Full OpenAPI V3 Kubernetes support was introduced in v1.27

We do not use go-openapi and have our own library in kube-openapi and client-go. This has full OpenAPI V3 support with additional features like caching and automatic GV parsing.

For the documentation generation, a live cluster is probably not needed and we can go purely based off the generated OpenAPI V3 files in k/k (https://github.com/kubernetes/kubernetes/tree/master/api/openapi-spec/v3). The project kubectl-validate already has code querying this repo (https://github.com/kubernetes-sigs/kubectl-validate/blob/main/pkg/openapiclient/github_builtins.go#L39) and it shouldn't be too difficult duplicating this IMO.

[sftim]

Help, especially around defining the work and helping break it into approachable chunks, is very welcome.

[tengqm]

Again, what are the benefits of OpenAPI v3 bring to the table? Say, it introduces "oneOf", "allOf" or "anyOf" to the spec. However, it is not used anywhere in a meaningful way other than the "IntOrString" data type. Nullable is another feature always mentioned by people. But the spec is not using it anywhere other than the CRD itself. Migrating the parser to V3 is not a trivial task. We have to weigh the benefits against the efforts. In fact, it is not a migration, it means reworking the parser.