docs: add custom object patch example

[YuqiGuo105]

Summary

• add a runnable example for patching namespaced custom objects through PatchUtils
• document why generated custom-object PATCH requests should not be executed directly
• accept the JSON Patch document as a file instead of hard-coding a resource-specific operation
• add HTTP-level tests for namespaced and cluster-scoped custom objects
• cover both JSON Patch and JSON Merge Patch media types

Problem

The generated CustomObjectsApi PATCH request defaults to Content-Type: application/json. Kubernetes PATCH endpoints require a patch-specific media type such as:

• application/json-patch+json
• application/merge-patch+json

Calling the generated request's execute() method directly can therefore result in 415 Unsupported Media Type, even when the patch document itself is valid.

Solution

The new PatchCustomObjectExample builds the generated custom-object request with buildCall(null) and executes it through PatchUtils.patch(...):

PatchUtils.patch(
    Object.class,
    () ->
        api.patchNamespacedCustomObject(
                group,
                version,
                namespace,
                plural,
                name,
                new V1Patch(patchJson))
            .buildCall(null),
    V1Patch.PATCH_FORMAT_JSON_PATCH,
    client);

The example reads the patch document from a user-provided file, so it does not assume a particular custom-resource schema or that optional metadata fields already exist.

The generated CustomObjectsApi.java and generated API documentation are intentionally left unchanged because those files would be overwritten during OpenAPI regeneration.

Tests

PatchUtilsTest now verifies that custom-object PATCH requests:

• use the namespaced custom-object URL
• preserve the original JSON Patch and JSON Merge Patch bodies
• send the requested patch-specific Content-Type
• deserialize the returned custom object
• use the correct cluster-scoped custom-object URL

Validation performed:

• ./mvnw -pl util,examples/examples-release-latest -am -Dtest=PatchUtilsTest -Dsurefire.failIfNoSpecifiedTests=false test
• ./mvnw spotless:check
• ./mvnw -pl util,examples/examples-release-latest -am clean test

Closes #3106.

[brendandburns]

/lgtm
/approve

[kubernetes-prow]

[APPROVALNOTIFIER] This PR is APPROVED

This pull-request has been approved by: brendandburns, YuqiGuo105

The full list of commands accepted by this bot can be found here.

The pull request process is described here

Details

Needs approval from an approver in each of these files:

• OWNERS [brendandburns]

Approvers can indicate their approval by writing /approve in a comment
Approvers can cancel approval by writing /approve cancel in a comment