Document Antrea public interfaces

[antoninbas]

We should publish (on antrea.io) auto-generated documentation for Antrea's public interfaces.

These public interfaces include:

• CRDs (NetworkPolicies, Traceflow, ...)
• APIServices other than controlplane, which is meant to be consumed internally by Antrea; since integrated solutions may want to consume controlplane as well, it could be a good idea to generate the documentation for it as well, potentially with a disclaimer that this is not considered a public API (in particular, when it comes to the deprecation policy)

This is part of the effort to obtain a passing CII best practices badge: #989

Ideally, the auto-generated documentation should look like the one for the K8s API: https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.19/

Some suggestions on how to generate the documentation:

1. follow the K8s model: generate the OpenAPI spec (for K8s: https://github.com/kubernetes/kubernetes/blob/master/api/openapi-spec/swagger.json, which is generated by https://github.com/kubernetes/kubernetes/blob/master/hack/update-openapi-spec.sh) and from there generate the web documentation for K8s: https://github.com/kubernetes-sigs/reference-docs/tree/master/gen-apidocs)
2. use a 3rd party project, https://github.com/ahmetb/gen-crd-api-reference-docs, which is used by other projects in the K8s ecosystem, e.g. Knative, cert-manager

The 1st solution requires running a K8s apiserver and connecting to it to retrieve the OpenAPI specs. It requires a complete validation schema for all the Antrea CRDs, which we do not have yet (but the plan is to reach that milestone by 0.11). I haven't looked at how it would work for APIServices. My guess would be that we would need to run the Antrea apiserver as well (so essentially we would need to deploy Antrea in a K8s cluster, just for the sake of generating the documentation...) and retrieve the OpenAPI specs through the aggregation layer. Not 100% sure what else would be needed for the OpenAPI specs to be served correcly.

The 2nd solution should work well for all the Antrea APIs. It may not be as flexible as generating a full-fledged OpenAPI spec (like swagger.json for K8s) but it could be a good place to start. gen-crd-api-reference-docs generates a HTML file for each API group, that we can add to the antrea.io website (it will pick up the CSS from the website). My plan is to prototype this solution first. The only issue is that gen-crd-api-reference-docs does not seem very well documented.

[antoninbas]

Submitted a PR to add a wrapper script around gen-crd-api-reference-docs: #1507

The generated API reference doc is already available on the Antrea website: https://antrea.io/docs/master/api-reference/. I see some room for improvement, in particular I don't think we have quite enough comments in the Go source.

[github-actions]

This issue is stale because it has been open 180 days with no activity. Remove stale label or comment, or this will be closed in 180 days

[github-actions]

This issue is stale because it has been open 180 days with no activity. Remove stale label or comment, or this will be closed in 180 days