RuntimeSDK: Improve Runtime Hook Swagger documentation

[sbueringer]

User Story

As a user I would like to be able to get sufficient self-explanatory information to implement RuntimeHooks via the generated Swagger documentation/specification.

Detailed Description

This is a follow-up to #6455 (specifically: #6455 (comment) & #6455 (comment)). Goal of this issue is to extend the godoc comments of the request/response types and the description of the Hook (specified when registering the hook).

We should document things like:

• when is the hook triggered
• additional comments about how responses should be calculated, which fields are mandatory, ...
• ...

Note:

• This definitely applies to the Discovery hook, potentially to the other hooks we will add as well.

/kind cleanup
/area runtime-sdk

[fabriziopandini]

/milestone v1.2

[sbueringer]

As the RuntimeSDK documentation has been merged now, it's probably time to revisit this issue.

I'm not sure how much we want to document per hook in the Swagger schema, given the more extensive documentation we have in the book now (afaik we can only use plain strings for documentation in the schema).

We also already did a few rounds of improving descriptions/godocs of the hook API types, which are also reflected in the Swagger schema.

Is there anything else that we should do apart from re-reading the schema and see if makes sense as it is rendered in the Swagger-UI?

@fabriziopandini Opinions?

P.S. I think the current schema we have is already pretty good / maybe even better then what we have for our CRDs (especially considering that RuntimeSDK and the hooks are an experimental alpha feature)

[fabriziopandini]

Let me make a pass on the current swagger doc in the beta releases, then I will come back

[sbueringer]

Let me make a pass on the current swagger doc in the beta releases, then I will come back

Okay, thx.
The latest doc now also has links to the latest YAML in SwaggerUI: https://main.cluster-api.sigs.k8s.io/tasks/experimental-features/runtime-sdk/implement-lifecycle-hooks.html

[fabriziopandini]

/close

rif #6878

[k8s-ci-robot]

@fabriziopandini: Closing this issue.

In response to this:

/close

rif #6878

Instructions for interacting with me using PR comments are available here. If you have questions or suggestions related to my behavior, please file an issue against the kubernetes/test-infra repository.