docs: Avoid omitempty with kubebuilder:validation:Required

When writing a unionDiscriminator, use of ",omitempty" in the JSON
spec overrides any attempt to require the discriminator via the tag
+kubebuilder:validation:Required.  It is confusing to have the docs
recommend two conflicting pieces of information for the same field,
and it makes more sense for the discriminator to be mandatory (even
though, as correctly pointed out below, all of the other fields of the
union type must be optional).

See also kubernetes-sigs/kubebuilder#3794,
where a debate was held on whether kubebuilder should document the
interplay, which in turn pointed back to controller-tools conventions.

Signed-off-by: Eric Blake <[email protected]>

dev-guide/api-conventions.md

@@ -303,7 +303,7 @@ type MyPlatformConfig struct {
   // +unionDiscriminator
   // +kubebuilder:validation:Enum:="AWS";"Azure";"GCP"
   // +kubebuilder:validation:Required
-  PlatformType string `json:"platformType,omitempty"`
+  PlatformType string `json:"platformType"`
 
   // AWS is the AWS configuration.
   // All structures within the union must be optional and pointers.