kubernetes-sigs
Documentation not generated for non-standard API operations
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.
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
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.
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?
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.
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.
@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.
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.
/retitle Documentation not generated for non-standard API operations /kind bug
