kubernetes-sigs
Use OpenAPI V3 for documentation generation
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.
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/
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.
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.
Help, especially around defining the work and helping break it into approachable chunks, is very welcome.
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.
The Kubernetes project currently lacks enough contributors to adequately respond to all issues.
This bot triages un-triaged issues according to the following rules:
- After 90d of inactivity,
lifecycle/staleis applied - After 30d of inactivity since
lifecycle/stalewas applied,lifecycle/rottenis applied - After 30d of inactivity since
lifecycle/rottenwas applied, the issue is closed
You can:
- Mark this issue as fresh with
/remove-lifecycle stale - Close this issue with
/close - Offer to help out with Issue Triage
Please send feedback to sig-contributor-experience at kubernetes/community.
/lifecycle stale
The Kubernetes project currently lacks enough active contributors to adequately respond to all issues.
This bot triages un-triaged issues according to the following rules:
- After 90d of inactivity,
lifecycle/staleis applied - After 30d of inactivity since
lifecycle/stalewas applied,lifecycle/rottenis applied - After 30d of inactivity since
lifecycle/rottenwas applied, the issue is closed
You can:
- Mark this issue as fresh with
/remove-lifecycle rotten - Close this issue with
/close - Offer to help out with Issue Triage
Please send feedback to sig-contributor-experience at kubernetes/community.
/lifecycle rotten
The Kubernetes project currently lacks enough active contributors to adequately respond to all issues and PRs.
This bot triages issues according to the following rules:
- After 90d of inactivity,
lifecycle/staleis applied - After 30d of inactivity since
lifecycle/stalewas applied,lifecycle/rottenis applied - After 30d of inactivity since
lifecycle/rottenwas applied, the issue is closed
You can:
- Reopen this issue with
/reopen - Mark this issue as fresh with
/remove-lifecycle rotten - Offer to help out with Issue Triage
Please send feedback to sig-contributor-experience at kubernetes/community.
/close not-planned
@k8s-triage-robot: Closing this issue, marking it as "Not Planned".
In response to this:
The Kubernetes project currently lacks enough active contributors to adequately respond to all issues and PRs.
This bot triages issues according to the following rules:
- After 90d of inactivity,
lifecycle/staleis applied- After 30d of inactivity since
lifecycle/stalewas applied,lifecycle/rottenis applied- After 30d of inactivity since
lifecycle/rottenwas applied, the issue is closedYou can:
- Reopen this issue with
/reopen- Mark this issue as fresh with
/remove-lifecycle rotten- Offer to help out with Issue Triage
Please send feedback to sig-contributor-experience at kubernetes/community.
/close not-planned
Instructions for interacting with me using PR comments are available here. If you have questions or suggestions related to my behavior, please file an issue against the kubernetes-sigs/prow repository.
