search

istio / api

API definitions for the Istio project
Apache License 2.0
460 stars 558 forks source link

Better user-centric API documentation #3280

Open howardjohn opened 3 months ago

howardjohn commented 3 months ago

Currently, our API docs (https://istio.io/latest/docs/reference/config/networking/virtual-service/) are not well suited for human consumption IMO.

The structure of the docs is based on proto. Users interacting with Istio, however, do not use proto - they use YAML. Something like HTTPRouteDestination is confusing -- a user literally never sees this! The primary way a user can construct an actual YAML is by copying examples and tweaking them, as the docs themselves only loosely correlate to the YAML.

Additionally, we end up with multiple docs. For example, HTTPRewrite object has one description, and the field rewrite has a different one -- to a user, logically these are the same.

Another minor issue is I cannot link to an individual field (hence I could not link to rewrite directly).

We have one column for "required" or not, but its not always accurate, and doesn't fully represent the api validation logic.

Prior art (not saying these are good or bad necessarily, just some examples(:

https://doc.crds.dev/github.com/istio/api/extensions.istio.io/WasmPlugin/v1alpha1@1.22.2

https://developer.hashicorp.com/consul/docs/connect/config-entries/ingress-gateway

https://linkerd.io/2.15/reference/httproute/

https://gateway-api.sigs.k8s.io/reference/spec/#gateway.networking.k8s.io/v1.HTTPRoute

https://github.com/kubernetes-sigs/gateway-api/pull/3204

https://www.envoyproxy.io/docs/envoy/latest/api-v3/config/listener/v3/listener_components.proto

zirain commented 3 months ago

Right now, there's another issue we may want to support: it's hard to share a link on a field.