Use OpenAPI docs to generate reference docs

[evankanderson]

Expected Behavior

https://knative.dev/docs/reference/api/ are based on the exported OpenAPI definitions:

• https://github.com/knative/serving/blob/main/config/core/300-resources/service.yaml (et al)
• https://github.com/knative/eventing/blob/main/config/core/resources/broker.yaml (et al)

These should be able to be filtered by API group, so only non-internal APIs are documented. Kubernetes has a tool for this here: https://github.com/kubernetes-sigs/reference-docs Documentation on its use is here: https://kubernetes.io/docs/contribute/generate-ref-docs/kubernetes-api/

Actual Behavior

We use the script here: https://github.com/knative/docs/blob/main/hack/gen-api-reference-docs.sh, which uses the custom tool here: https://github.com/ahmetb/gen-crd-api-reference-docs

This builds output based on the Go structures, ignoring any OpenAPI validation or fields that we don't support. Also, the resulting output bleeds through Go structure embedding, making it harder for non-Go developers to understand the shape of the API.

Steps to Reproduce the Problem

1. Follow directions here: https://knative.dev/help/maintainer/building-api-output/

Additional Info

This is not high-priority at the moment, but since the OpenAPI docs are clearer about which fields are and are not supported, this would fix #2085

[abrennan89]

@evankanderson is the plan still to implement this? Any updates?

[abrennan89]

Closing this issue since there's been no work on it and I don't think there's anyone who wants to own this. Also, the related issue mentioned in the description is now closed. @evankanderson feel free to reopen if you plan to work on this.

[nak3]

/reopen

https://github.com/knative/serving/issues/12410#issuecomment-1464954879 got the request which is most probably same with here.

[knative-prow[bot]]

@nak3: Reopened this issue.

In response to this:

/reopen

https://github.com/knative/serving/issues/12410#issuecomment-1464954879 got the request which is most probably same with here.

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/test-infra repository.