Documentation not generated for non-standard API operations

[dshebib]

Reference: https://github.com/kubernetes/website/issues/39259

There are non-standard operations which are listed in the OpenAPI specification for which the website API reference is not generated, e.g. pods/exec and pods/attach.

[dshebib]

/assign

[dshebib]

It seems that the source of this issue is that the x-kubernetes-group-version-kind field does not match the definition url, for example:

"/api/v1/namespaces/{namespace}/pods/{name}/exec": { "get": { "consumes": [ "*/*" ], "description": "connect GET requests to exec of Pod", "operationId": "connectCoreV1GetNamespacedPodExec", "produces": [ "*/*" ], "responses": { "200": { "description": "OK", "schema": { "type": "string" } }, "401": { "description": "Unauthorized" } }, "schemes": [ "https" ], "tags": [ "core_v1" ], "x-kubernetes-action": "connect", "x-kubernetes-group-version-kind": { "group": "", "kind": "PodExecOptions", "version": "v1" } }, instead of "kind": "Pod"

It also is a 'connect' action, which is currently not documented in the API reference.

Given that this seems to be intentional, should we be fixing this? @tengqm

[tengqm]

right. The API spec contains several non-resource urls. If we want to support those paths, the generator needs a fix which won't be a trivial one.

[dshebib]

See #354, it seems that the existing functionality for specifying operation categories allows the generator to pickup even non-standard operations based on a regex on the operation id.

After getting to know the code though I'm interested in fixing how the generator finds operations based on resource URL's. Do you have any others in mind that aren't getting generated and wouldn't be able to be added using this method?

[tengqm]

I was not saying that this is not doable. We will need to consider the larger picture that not all endpoints are related to kubernetes resources. If we want to add support to the operations you mentioned, we can generalize the logic to cover all non-resource endpoints. That was the reason why I thought it a non-trivial task. I'm more than happy to see what we can do in this space.

[dshebib]

See #363. Because the generator already parses all the operations, I just added a new section for those endpoints not associated with a resource or definition.

[dshebib]

@tengqm There is another issue however that might require a rewrite. Currently we are using regex to match endpoint ID's to their associated resources, but this is subject to collision errors when there are two ID's which match to the same resource definition. If an endpoint or a resource is added which causes such a collision it could cause problems later on. I'd like to brainstorm potential ways to fix this together if you are willing.

[tengqm]

The chance of having two ID's matching the same resource definition would be pretty low. The operation IDs are generated by combinding verbs, resources and "sub-resources". I think it should be fine at the moment.

[sftim]

/retitle Documentation not generated for non-standard API operations /kind bug

[k8s-triage-robot]

The Kubernetes project currently lacks enough contributors to adequately respond to all issues.

This bot triages un-triaged issues according to the following rules:

• After 90d of inactivity, lifecycle/stale is applied
• After 30d of inactivity since lifecycle/stale was applied, lifecycle/rotten is applied
• After 30d of inactivity since lifecycle/rotten was applied, the issue is closed

You can:

• Mark this issue as fresh with /remove-lifecycle stale
• Close this issue with /close
• Offer to help out with Issue Triage

Please send feedback to sig-contributor-experience at kubernetes/community.

/lifecycle stale