Generate API reference in docs

[tnozicka]

At this point, our docs have an outdated example of ScyllaCluster API. This is historical, manually written and outdated. We also have more APIs / CRs then just ScyllaClusters.

Doing this manually is unmaintainable. But there is a way to generate the API docs automatically, as many sites do, like

• OpenShift API reference
• Kubernetes API reference

With some effort we can get swagger / openapi for our CRDs which can be used with an existing API docs generator. Given we use shpinx, https://github.com/sphinx-contrib/openapi would seem like a natural choice but it didn't work when I tried (see sphinx-contrib/openapi#144) for details.

If that doesn't get fixed we could generate markdown, like kube does https://github.com/kubernetes/website/blob/5c744748410a7f1d4ebaa03800ace6c2c4f672e2/content/en/blog/_posts/2020-12-04-gsod-2020-improving-api-reference-experience.md#markdown-pages

[tnozicka]

@dgarcia360 @annastuchlik do you know whether we generate API reference docs from OpenAPI anywhere else with our sphinx theme?

[dgarcia360]

Hi @tnozicka,

We are generating OpenAPI docs for the Scylla Cloud Docs project with a custom extension we could reuse. It's based on Redocly.

During the following weeks, we are working with https://github.com/scylladb/scylladb to generate API Reference docs based on an OpenAPI v3 spec too. I think it might be a good time to make this extension as part of the theme (scylladb/sphinx-scylladb-theme#722)

Could you define the API for scylla-operator using OpenAPI v3? In the meantime, I can help setting up the tooling for generating the docs.

[tnozicka]

Thanks @dgarcia360, I have looked into the API docs for cloud and I don't think pure swagger would cut it for us.

Our API (based on kube-apiserver and CRD) is uniform and we can live without describing the REST details but, from what I've collected, we need it to:

• be aware of API groups
• be aware of API versions
• not to inline common types in the same API group and other API group (this info isn't present in OpenAPI or CRDs)

Just a note, that we don't care too much about explaining the authentication or REST details as that's common to Kubernetes which we can reference and almost everyone uses common kubectl that wraps it. (It would be nice but probably to much effort for little gain at this point.)

I've done rst gotemplate in #1541 to get us 95% but to avoid the inlines we'll have to parse the Golang types similarly to Kube or OpenShift to get the extra info.