feat: support @JsonClassDescription for top-level CRD description (#7375)

[taole33]

Description

This PR introduces support for the Jackson @JsonClassDescription annotation to provide a top-level description for generated Custom Resource Definitions (CRDs), addressing the request in #7375.

Previously, only property-level descriptions via @JsonPropertyDescription were supported. With this change, both v1 and v2 CRD generators can now extract and include the description at the root of the OpenAPI v3 schema when a Custom Resource class is annotated with @JsonClassDescription.

Changes

• Modified AbstractJsonSchema in crd-generator-api (v1) and crd-generator-api-v2 to process class-level annotations.
• Added a new dedicated test case in crd-generator/test using a sample Described resource to verify the output YAML across all supported CRD versions.
• Ensured consistency between v1 and v2 generator engines.

Type of change

• Feature (non-breaking change which adds functionality)

Checklist

• Code contributed by me aligns with current project license: [Apache 2.0](https://www.apache.org/licenses/LICENSE-2.0)
• I Added [CHANGELOG](https://github.com/fabric8io/kubernetes-client/blob/main/CHANGELOG.md) entry regarding this change
• I have implemented unit tests to cover my changes
• I have added/updated the [javadocs](https://www.javadoc.io/doc/io.fabric8/kubernetes-client/latest/index.html) and other [documentation](https://github.com/fabric8io/kubernetes-client/blob/main/doc/CHEATSHEET.md) accordingly
• No new bugs, code smells, etc. in [SonarCloud](https://sonarcloud.io/dashboard?id=fabric8io_kubernetes-client) report
• I tested my code in Kubernetes
• I tested my code in OpenShift

Fixes #7375

[shawkins]

Thank you for the PR, it looks very good.

Just wanted to add that it's not required to make changes to the older implementation. You can just add a v2 generator specific test.

[shawkins]

This doesn't appear to be used.

[taole33]

@shawkins
I'll revert the changes in the v1 implementation to keep the legacy code base untouched and will update the PR to focus solely on the v2 generator and its specific tests. Thanks for the guidance!

[taole33]

@shawkins
I have updated the PR to focus the @JsonClassDescription support exclusively on the v2 generator. The v1 logic has been reverted and restored to its original state.

[taole33]

@shawkins
I have pushed the following updates to address the recent CI errors:

• License Header Fix: Applied mvn -N license:format to ensure all new files comply with the project's license requirements.

• Regarding the "Kubernetes Model Generator Build" failure, I have validated the same CI-test in my repository and confirmed it passes successfully.

All CI checks should be green now. Thanks for waiting.

[shawkins]

This looks great. The only nit would be that the description annotation is used at any level, not just the top-level object.

Could the changelog and a doc entry in https://github.com/fabric8io/kubernetes-client/blob/main/doc/CRD-generator.md#features-cheatsheet be updated to reflect this?

[taole33]

@shawkins

Could the changelog and a doc entry in https://github.com/fabric8io/kubernetes-client/blob/main/doc/CRD-generator.md#features-cheatsheet be updated to reflect this?

Sure, I’d be happy to update the changelog and documentation.
I also noticed the CI failure, so I will investigate the cause.

[taole33]

@shawkins Thank you for the feedback.

I have updated the documentation and the features cheatsheet in CRD-generator.md.

While updating the docs, I discovered and fixed a logic issue in AbstractJsonSchema where a class-level description was being overwritten by a null property description when @JsonPropertyDescription was absent. This fix ensures that @JsonClassDescription is correctly preserved for all object types, including nested ones.

I have also synchronized this branch with the latest upstream changes. Please let me know if you have any further comments.

[shawkins]

Thank you for the latest changes.

While updating the docs, I discovered and fixed a logic issue in AbstractJsonSchema where a class-level description was being overwritten by a null property description when @JsonPropertyDescription was absent.

The logic hadn't needed to consider this case before. The update you made is appropriate and effectively makes the class description the default for the field description. I think this makes sense, but if any of the other reviewers feel otherwise we'll revisit it.

[taole33]

Thanks for the approval, @shawkins!

Regarding the CI failure in the 'Build' job, it seems unrelated to these changes (appears to be a flaky test).

I have analyzed both the Java 11 and Java 21 CI logs. The failure in ConfigRefreshTest occurs within the kubernetes-client core module, which is upstream of the crd-generator module I modified. Since the build failed before even reaching my changes, it appears to be a pre-existing flaky issue in the CI environment.

Could someone from the team please re-run the failed jobs? Thank you!