CRDGenerator: Support for externalDocs

[baloo42]

Is your enhancement related to a problem? Please describe

The JSONSchemaProps in CRDs allow to reference external documentation resources:

https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.31/#externaldocumentation-v1-apiextensions-k8s-io

The CRDGenerator should be able to generate those references by searching for an annotation.

Describe the solution you'd like

Suggested annotation:

@Target({ ElementType.TYPE, ElementType.METHOD, ElementType.FIELD, ElementType.ANNOTATION_TYPE })
@Retention(RetentionPolicy.RUNTIME)
public @interface ExternalDocs {

  /**
   * A short description of the target documentation.
   *
   * @return the documentation description
   **/
  String description() default "";

  /**
   * The URL for the target documentation. Value must be in the format of a URL.
   *
   * @return the documentation URL
   **/
  String url() default "";

}

externalDocs should only appear in the resulting schema if at least url or description is not empty.

Describe alternatives you've considered

No response

Additional context

Example tests:
https://github.com/baloo42/crd-generator-victools/blob/main/test/src/test/java/io/fabric8/crd/generator/victools/approvaltests/externaldocs/ExternalDocSpec.java
https://github.com/baloo42/crd-generator-victools/blob/main/test/src/test/resources/io/fabric8/crd/generator/victools/approvaltests/CRDGeneratorVictoolsApprovalTest.approvalTest.externaldocs.samples.fabric8.io.v1.approved.yml

[stale]

This issue has been automatically marked as stale because it has not had any activity since 90 days. It will be closed if no further activity occurs within 7 days. Thank you for your contributions!