✨ Add Title marker (#1175)

* feat: add title marker

* tests: add validation fail tests

* test: change test name

Author: matteogastaldello

pkg/crd/markers/validation.go

@@ -103,6 +103,9 @@ var FieldOnlyMarkers = []*definitionWithHelp{
 
 	must(markers.MakeDefinition(SchemalessName, markers.DescribesField, Schemaless{})).
 		WithHelp(Schemaless{}.Help()),
+
+	must(markers.MakeAnyTypeDefinition("kubebuilder:title", markers.DescribesField, Title{})).
+		WithHelp(Title{}.Help()),
 }
 
 // ValidationIshMarkers are field-and-type markers that don't fall under the
@@ -242,6 +245,17 @@ type Default struct {
 	Value interface{}
 }
 
+// +controllertools:marker:generateHelp:category="CRD validation"
+// Title sets the title for this field.
+//
+// The title is metadata that makes the OpenAPI documentation more user-friendly,
+// making the schema more understandable when viewed in documentation tools.
+// It's a metadata field that doesn't affect validation but provides
+// important context about what the schema represents.
+type Title struct {
+	Value interface{}
+}
+
 // +controllertools:marker:generateHelp:category="CRD validation"
 // Default sets the default value for this field.
 //
@@ -527,6 +541,19 @@ func (m Default) ApplyPriority() ApplyPriority {
 	return 10
 }
 
+func (m Title) ApplyToSchema(schema *apiext.JSONSchemaProps) error {
+	if m.Value == nil {
+		// only apply to the schema if we have a non-nil title
+		return nil
+	}
+	title, isStr := m.Value.(string)
+	if !isStr {
+		return fmt.Errorf("expected string, got %T", m.Value)
+	}
+	schema.Title = title
+	return nil
+}
+
 func (m *KubernetesDefault) ParseMarker(_ string, _ string, restFields string) error {
 	if strings.HasPrefix(strings.TrimSpace(restFields), "ref(") {
 		// Skip +default=ref(...) values for now, since we don't have a good way to evaluate go constant values via AST.

pkg/crd/markers/zz_generated.markerhelp.go

@@ -187,6 +187,19 @@ var _ = Describe("CRD Generation From Parsing to CustomResourceDefinition", func
 			})
 		})
 
+		Context("Field with unvalid title format", func() {
+			BeforeEach(func() {
+				pkgPaths = []string{"./wrong_title_format"}
+				expPkgLen = 1
+			})
+			It("cannot generate title field from integer", func() {
+				assertError(pkgs[0], "JobSpec", "expected string, got int")
+			})
+			It("cannot generate title field from map", func() {
+				assertError(pkgs[0], "TestType", "expected string, got map[string]interface {}")
+			})
+		})
+
 		Context("CronJob API without group", func() {
 			BeforeEach(func() {
 				pkgPaths = []string{"./nogroup"}

pkg/crd/parser_integration_test.go

@@ -113,20 +113,24 @@ type CronJobSpec struct {
 	// This tests that primitive defaulting can be performed.
 	// +kubebuilder:default=forty-two
 	// +kubebuilder:example=forty-two
+	// +kubebuilder:title=DefaultedString
 	DefaultedString string `json:"defaultedString"`
 
 	// This tests that slice defaulting can be performed.
 	// +kubebuilder:default={a,b}
 	// +kubebuilder:example={a,b}
+	// +kubebuilder:title=DefaultedSlice
 	DefaultedSlice []string `json:"defaultedSlice"`
 
 	// This tests that slice and object defaulting can be performed.
 	// +kubebuilder:default={{nested: {foo: "baz", bar: true}},{nested: {foo: "qux", bar: false}}}
 	// +kubebuilder:example={{nested: {foo: "baz", bar: true}},{nested: {foo: "qux", bar: false}}}
+	// +kubebuilder:title="124"
 	DefaultedObject []RootObject `json:"defaultedObject"`
 
 	// This tests that empty slice defaulting can be performed.
 	// +kubebuilder:default={}
+	// +kubebuilder:title="{}"
 	DefaultedEmptySlice []string `json:"defaultedEmptySlice"`
 
 	// This tests that an empty object defaulting can be performed on a map.

pkg/crd/testdata/cronjob_types.go

@@ -131,6 +131,7 @@ spec:
                 description: This tests that empty slice defaulting can be performed.
                 items:
                   type: string
+                title: '{}'
                 type: array
               defaultedObject:
                 default:
@@ -163,6 +164,7 @@ spec:
                   required:
                   - nested
                   type: object
+                title: "124"
                 type: array
               defaultedSlice:
                 default:
@@ -174,11 +176,13 @@ spec:
                 - b
                 items:
                   type: string
+                title: DefaultedSlice
                 type: array
               defaultedString:
                 default: forty-two
                 description: This tests that primitive defaulting can be performed.
                 example: forty-two
+                title: DefaultedString
                 type: string
               doubleDefaultedString:
                 default: kubebuilder-default

pkg/crd/testdata/testdata.kubebuilder.io_cronjobs.yaml

@@ -0,0 +1,65 @@
+/*
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+*/
+
+// +groupName=testdata.kubebuilder.io
+// +versionName=v1beta1
+package job
+
+import (
+	metav1 "k8s.io/apimachinery/pkg/apis/meta/v1"
+
+	"testdata.kubebuilder.io/cronjob/unserved"
+)
+
+// +kubebuilder:object:root=true
+// +kubebuilder:subresource:status
+// +kubebuilder:resource:singular=job
+
+type TestType struct {
+	// Count is the number of times a job may be executed.
+	//
+	// +kubebuilder:title={}
+	Count int32 `json:"count"`
+}
+
+// JobSpec is the spec for the jobs API.
+type JobSpec struct {
+	// FriendlyName is the friendly name for the job.
+	//
+	// +kubebuilder:title=123
+	FriendlyName string `json:"friendlyName"`
+
+	// CronJob is the spec for the related CrongJob.
+	CronnJob unserved.CronJobSpec `json:"crongJob"`
+}
+
+// Job is the Schema for the jobs API
+type Job struct {
+	/*
+	 */
+	metav1.TypeMeta   `json:",inline"`
+	metav1.ObjectMeta `json:"metadata,omitempty"`
+
+	Spec JobSpec `json:"spec"`
+}
+
+// +kubebuilder:object:root=true
+
+// JobList contains a list of Job
+type JobList struct {
+	metav1.TypeMeta `json:",inline"`
+	metav1.ListMeta `json:"metadata,omitempty"`
+	Items           []Job `json:"items"`
+}