Merge pull request #299 from droot/feature/limit-description

Limiting description of fields in CRD's OpenAPI Schema

Author: k8s-ci-robot

pkg/crd/desc_visitor.go

@@ -0,0 +1,78 @@
+/*
+Copyright 2019 The Kubernetes Authors.
+
+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.
+*/
+
+package crd
+
+import (
+	"strings"
+	"unicode"
+
+	apiext "k8s.io/apiextensions-apiserver/pkg/apis/apiextensions/v1beta1"
+)
+
+// TruncateDescription truncates the description of fields in given schema if it
+// exceeds maxLen.
+// It tries to chop off the description at the closest sentence boundary.
+func TruncateDescription(schema *apiext.JSONSchemaProps, maxLen int) {
+	EditSchema(schema, descVisitor{maxLen: maxLen})
+}
+
+// descVisitor recursively visits all fields in the schema and truncates the
+// description of the fields to specified maxLen.
+type descVisitor struct {
+	// maxLen is the maximum allowed length for decription of a field
+	maxLen int
+}
+
+func (v descVisitor) Visit(schema *apiext.JSONSchemaProps) SchemaVisitor {
+	if schema == nil {
+		return v
+	}
+	if v.maxLen < 0 {
+		return nil /* no further work to be done for this schema */
+	}
+	if v.maxLen == 0 {
+		schema.Description = ""
+		return v
+	}
+	if len(schema.Description) > v.maxLen {
+		schema.Description = truncateString(schema.Description, v.maxLen)
+		return v
+	}
+	return v
+}
+
+// truncateString truncates given desc string if it exceeds maxLen. It may
+// return string with length less than maxLen even in cases where original desc
+// exceeds maxLen because it tries to chop off the desc at the closest sentence
+// boundary to avoid incomplete sentences.
+func truncateString(desc string, maxLen int) string {
+	desc = desc[0:maxLen]
+
+	// Trying to chop off at closest sentence boundary.
+	if n := strings.LastIndexFunc(desc, isSentenceTerminal); n > 0 {
+		return desc[0 : n+1]
+	}
+	// TODO(droot): Improve the logic to chop off at closest word boundary
+	// or add elipses (...) to indicate that it's chopped incase no closest
+	// sentence found within maxLen.
+	return desc
+}
+
+// helper function to determine if given rune is a sentence terminal or not.
+func isSentenceTerminal(r rune) bool {
+	return unicode.Is(unicode.STerm, r)
+}

pkg/crd/desc_visitor_test.go

@@ -0,0 +1,81 @@
+/*
+Copyright 2019 The Kubernetes Authors.
+
+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.
+*/
+
+package crd_test
+
+import (
+	. "github.com/onsi/ginkgo"
+	. "github.com/onsi/gomega"
+
+	apiext "k8s.io/apiextensions-apiserver/pkg/apis/apiextensions/v1beta1"
+
+	"sigs.k8s.io/controller-tools/pkg/crd"
+)
+
+var _ = Describe("TruncateDescription", func() {
+
+	It("should drop the description for all fields for zero value of maxLen", func() {
+		schema := &apiext.JSONSchemaProps{
+			Description: "top level description",
+			Properties: map[string]apiext.JSONSchemaProps{
+				"Spec": apiext.JSONSchemaProps{
+					Description: "specification for the API type",
+				},
+			},
+		}
+		crd.TruncateDescription(schema, 0)
+		Expect(schema).To(Equal(&apiext.JSONSchemaProps{
+			Properties: map[string]apiext.JSONSchemaProps{
+				"Spec": apiext.JSONSchemaProps{},
+			},
+		}))
+
+	})
+
+	It("should truncate the description only in cases where description exceeds maxLen", func() {
+		schema := &apiext.JSONSchemaProps{
+			Description: "top level description of the root object.",
+			Properties: map[string]apiext.JSONSchemaProps{
+				"Spec": apiext.JSONSchemaProps{
+					Description: "specification of a field",
+				},
+			},
+		}
+		original := schema.DeepCopy()
+		crd.TruncateDescription(schema, len(schema.Description))
+		Expect(schema).To(Equal(original))
+	})
+
+	It("should truncate the description at closest sentence boundary", func() {
+		schema := &apiext.JSONSchemaProps{
+			Description: `This is top level description. There is an empty schema. More to come`,
+		}
+		crd.TruncateDescription(schema, len(schema.Description)-5)
+		Expect(schema).To(Equal(&apiext.JSONSchemaProps{
+			Description: `This is top level description. There is an empty schema.`,
+		}))
+	})
+
+	It("should truncate the description at maxLen in absence of sentence boundary", func() {
+		schema := &apiext.JSONSchemaProps{
+			Description: `This is top level description of the root object`,
+		}
+		crd.TruncateDescription(schema, len(schema.Description)-2)
+		Expect(schema).To(Equal(&apiext.JSONSchemaProps{
+			Description: `This is top level description of the root obje`,
+		}))
+	})
+})

pkg/crd/gen.go

@@ -39,6 +39,13 @@ type Generator struct {
 	// Kubernetes API servers.  The storage version's schema will be used as
 	// the CRD's schema.
 	TrivialVersions bool `marker:",optional"`
+
+	// MaxDescLen limits the description length of each field in CRD's OpenAPI schema.
+	//
+	// nil (default) indicates no limit on description of fields
+	// 0 indicates drop the description completely
+	// n means at most n characters
+	MaxDescLen *int `marker:",optional"`
 }
 
 func (Generator) RegisterMarkers(into *markers.Registry) error {
@@ -69,7 +76,7 @@ func (g Generator) Generate(ctx *genall.GenerationContext) error {
 	}
 
 	for _, groupKind := range kubeKinds {
-		parser.NeedCRDFor(groupKind)
+		parser.NeedCRDFor(groupKind, g.MaxDescLen)
 		crd := parser.CustomResourceDefinitions[groupKind]
 		if g.TrivialVersions {
 			toTrivialVersions(&crd)

pkg/crd/parser_integration_test.go

@@ -79,7 +79,7 @@ var _ = Describe("CRD Generation From Parsing to CustomResourceDefinition", func
 
 		By("requesting that the CRD be generated")
 		groupKind := schema.GroupKind{Kind: "CronJob", Group: "testdata.kubebuilder.io"}
-		parser.NeedCRDFor(groupKind)
+		parser.NeedCRDFor(groupKind, nil)
 
 		By("checking that no errors occurred along the way (expect for type errors)")
 		Expect(packageErrors(cronJobPkg, packages.TypeError)).NotTo(HaveOccurred())

pkg/crd/spec.go

@@ -121,7 +121,7 @@ func MergeIdenticalVersionInfo(crd *apiext.CustomResourceDefinition) {
 // NeedCRDFor requests the full CRD for the given group-kind.  It requires
 // that the packages containing the Go structs for that CRD have already
 // been loaded with NeedPackage.
-func (p *Parser) NeedCRDFor(groupKind schema.GroupKind) {
+func (p *Parser) NeedCRDFor(groupKind schema.GroupKind, maxDescLen *int) {
 	p.init()
 
 	if _, exists := p.CustomResourceDefinitions[groupKind]; exists {
@@ -161,6 +161,9 @@ func (p *Parser) NeedCRDFor(groupKind schema.GroupKind) {
 			continue
 		}
 		fullSchema := FlattenEmbedded(p.flattener.FlattenType(typeIdent), pkg)
+		if maxDescLen != nil {
+			TruncateDescription(fullSchema, *maxDescLen)
+		}
 		ver := apiext.CustomResourceDefinitionVersion{
 			Name:   p.GroupVersions[pkg].Version,
 			Served: true,