Use OpenAPI docs to generate reference docs
- Dominant language
- HTML
- Stars
- 5.1k
- Forks
- 1.3k
- PR merge metrics
- No merged PRs in 30d
Description
## 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
Contributor guide
Research direction
Start with hack/gen-api-reference-docs.sh and the maintainer instructions for building API output. Compare the current custom generator with Kubernetes reference-docs and the exported OpenAPI definitions in the linked Knative repositories. Done means generating reference documentation from OpenAPI data while filtering out internal API groups and avoiding unsupported or misleading fields.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- go, kubernetes, openapi, shell
- Domain
- api, documentation
- Issue type
- Documentation
- Difficulty
- 5/5
- Estimated time
- Over a week
- Activity status
- Stale
- Clarity
- Mostly clear
- Newbie friendliness
- 25/100