feat(crd-generator): introduce @JSONSchema annotation

[MikeEdgar]

Description

Closes #6999

This is a POC to demonstrate the idea behind #6999 (it may also close several other issues related to the CRD generator's capabilities). The new @JSONSchema annotation may be used on a class or property to short-circuit other schema scanning for the target. The exception is when the annotation's implementation is used. In that case, the implementation class will be scanned as normal, then the @JSONSchema annotation attributes will be used to override those from the scan.

The annotation also includes a structural boolean attribute that enables certain handling for structural schemas. This includes copying properties from allOf, anyOf, oneOf, and not to the schema with the annotation, and also removing the restricted attributes without those sub-schemas.

Several of the attributes of the annotation may not actually be valid for a Kube CRD schema. However, the intent here is simply to expose the CRD schema model entirely to give that control to the user.

Type of change

• Bug fix (non-breaking change which fixes an issue)
• Feature (non-breaking change which adds functionality)
• Breaking change (fix or feature that would cause existing functionality to change
• Chore (non-breaking change which doesn't affect codebase;
  test, version modification, documentation, etc.)

Checklist

• Code contributed by me aligns with current project license: Apache 2.0
• I Added CHANGELOG entry regarding this change
• I have implemented unit tests to cover my changes
• I have added/updated the javadocs and other documentation accordingly
• No new bugs, code smells, etc. in SonarCloud report
• I tested my code in Kubernetes
• I tested my code in OpenShift

[MikeEdgar]

Still a work-in-progress, needs lots of testing and feedback/comments on whether this seems generally viable :)

[sonarqubecloud]

Quality Gate passed

Issues
1 New issue
0 Accepted issues

Measures
0 Security Hotspots
81.4% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud

[shawkins]

Thanks @MikeEdgar this looks promising.

It does seem highly related to SchemaSwap - at least for the usage of implemenation or type.

SchemaSwap could be altered to work at a field level, but one of the usage models it supports is for Keycloak, and maybe other projects, where the classes are defined in some other module and don't need or want CRD related annotations - so you are forced to define the swaps at a higher level than directly on the intended fields.

cc @andreaTP I know you have mentioned in the past wanted to see a general schema option - did you think of it working vis SchemaSwap or a separate annotation?

[MikeEdgar]

It does seem highly related to SchemaSwap - at least for the usage of implemenation or type.

Yes, I think the implementation attribute would be somewhat similar to SchemaSwap, but as you say the location is potentially different. The swaps are still limited to whatever schema can be obtained from the referenced class(es) using the existing scanning however, correct?

[shawkins]

The swaps are still limited to whatever schema can be obtained from the referenced class(es) using the existing scanning however, correct?

That is correct, you can't specify an arbitrary type in string form. I also forgot to mention SchemaFrom (the localized limited form of SchemaSwap). So instead of:

  @JSONSchema(type = "string")
  private Object customizedType;

You could do either:

  @SchemaFrom(type = String.class)
  private Object customizedType;

or

  @SchemaSwap(originalType = JsonSchemaAnnoSpec.class, targetField = "customizedType", targetType = String.class)
  ...

With a similar comparison for implementation.