knative / knative/docs

Use OpenAPI docs to generate reference docs

Open
#3,523 4 comments 0 reactions 0 assignees View on GitHub
kind/infrastructure kind/needs-automation lifecycle/frozen priority/medium triage/needs-eng-input
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

Open the contributing 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.