feat: add kubebuilder:externalDoc marker

Implement the `kubebuilder:externalDoc` marker to allow specifying
external documentation (url and description) on fields and types,
populating the externalDocs field in the generated OpenAPI schema
per the OpenAPI 3.0.0 External Documentation Object specification.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Author: pedjak

pkg/crd/markers/crd.go

@@ -57,6 +57,11 @@ var CRDMarkers = []*definitionWithHelp{
 
 	must(markers.MakeDefinition("kubebuilder:selectablefield", markers.DescribesType, SelectableField{})).
 		WithHelp(SelectableField{}.Help()),
+
+	must(markers.MakeDefinition("kubebuilder:externalDoc", markers.DescribesField, ExternalDoc{})).
+		WithHelp(ExternalDoc{}.Help()),
+	must(markers.MakeDefinition("kubebuilder:externalDoc", markers.DescribesType, ExternalDoc{})).
+		WithHelp(ExternalDoc{}.Help()),
 }
 
 // TODO: categories and singular used to be annotations types
@@ -419,3 +424,25 @@ func (s SelectableField) ApplyToCRD(crd *apiextensionsv1.CustomResourceDefinitio
 
 	return nil
 }
+
+// +controllertools:marker:generateHelp:category=CRD
+
+// ExternalDoc specifies external documentation for this field or type.
+//
+// The url is required and must be a valid URL. The description is optional
+// and provides a short description of the external documentation.
+type ExternalDoc struct {
+	// URL specifies the URL for the target documentation.
+	URL string `marker:"url"`
+
+	// Description is a short description of the target documentation.
+	Description string `marker:",optional"`
+}
+
+func (m ExternalDoc) ApplyToSchema(schema *apiextensionsv1.JSONSchemaProps) error {
+	schema.ExternalDocs = &apiextensionsv1.ExternalDocumentation{
+		URL:         m.URL,
+		Description: m.Description,
+	}
+	return nil
+}

pkg/crd/markers/zz_generated.markerhelp.go

@@ -224,6 +224,52 @@ var _ = Describe("CRD Generation From Parsing to CustomResourceDefinition", func
 			})
 		})
 
+		Context("ExternalDoc API", func() {
+			BeforeEach(func() {
+				pkgPaths = []string{"./external_docs/..."}
+				expPkgLen = 1
+			})
+			It("should generate the CRD with external documentation and warn about link definition conflicts", func() {
+				By("requesting that the ExternalDoc CRD be generated")
+				groupKind := schema.GroupKind{Kind: "ExternalDoc", Group: "testdata.kubebuilder.io"}
+				parser.NeedCRDFor(groupKind, nil)
+
+				By("fixing top level ObjectMeta on the ExternalDoc CRD")
+				crd.FixTopLevelMetadata(parser.CustomResourceDefinitions[groupKind])
+
+				By("checking that expected warnings occurred")
+				var errMsgs []string
+				packages.Visit([]*packages.Package{pkgs[0].Package}, nil, func(pkgRaw *packages.Package) {
+					for _, err := range pkgRaw.Errors {
+						if err.Kind == packages.TypeError {
+							continue
+						}
+						errMsgs = append(errMsgs, err.Msg)
+					}
+				})
+				Expect(errMsgs).To(ContainElement(ContainSubstring("doc comment contains multiple link definitions for externalDoc")))
+				Expect(errMsgs).To(ContainElement(ContainSubstring("kubebuilder:externalDoc marker is set, but doc comment also contains link definitions")))
+
+				By("checking that the ExternalDoc CRD is present")
+				Expect(parser.CustomResourceDefinitions).To(HaveKey(groupKind))
+
+				By("loading the desired ExternalDoc YAML")
+				expectedFile, err := os.ReadFile("testdata.kubebuilder.io_externaldocs.yaml")
+				Expect(err).NotTo(HaveOccurred())
+
+				By("parsing the desired ExternalDoc YAML")
+				var expectedCRD apiextensionsv1.CustomResourceDefinition
+				Expect(yaml.Unmarshal(expectedFile, &expectedCRD)).To(Succeed())
+				delete(expectedCRD.Annotations, "controller-gen.kubebuilder.io/version")
+				if len(expectedCRD.Annotations) == 0 {
+					expectedCRD.Annotations = nil
+				}
+
+				By("comparing the two ExternalDoc CRDs")
+				Expect(parser.CustomResourceDefinitions[groupKind]).To(Equal(expectedCRD), "type not as expected, check pkg/crd/testdata/README.md for more details.\n\nDiff:\n\n%s", cmp.Diff(parser.CustomResourceDefinitions[groupKind], expectedCRD))
+			})
+		})
+
 		Context("CronJob API without group", func() {
 			BeforeEach(func() {
 				pkgPaths = []string{"./nogroup"}

pkg/crd/parser_integration_test.go

@@ -20,6 +20,7 @@ import (
 	"errors"
 	"fmt"
 	"go/ast"
+	"go/doc/comment"
 	"go/token"
 	"go/types"
 	"slices"
@@ -213,6 +214,56 @@ func applyMarkers(ctx *schemaContext, markerSet markers.MarkerValues, props *api
 	}
 }
 
+// parseLinkDefs parses Go 1.19+ link definitions from a doc comment string.
+func parseLinkDefs(doc string) []*comment.LinkDef {
+	if doc == "" {
+		return nil
+	}
+	var p comment.Parser
+	d := p.Parse(doc)
+	return d.Links
+}
+
+// applyDocLinkDef sets ExternalDocs from doc comment link definitions.
+// It warns if multiple link defs are found or if both a marker and link defs exist.
+func applyDocLinkDef(ctx *schemaContext, props *apiextensionsv1.JSONSchemaProps, doc string, node ast.Node) {
+	links := parseLinkDefs(doc)
+	if len(links) == 0 {
+		return
+	}
+
+	formatLinkDefs := func() string {
+		parts := make([]string, len(links))
+		for i, l := range links {
+			parts[i] = fmt.Sprintf("[%s]: %s", l.Text, l.URL)
+		}
+		return strings.Join(parts, ", ")
+	}
+
+	if props.ExternalDocs != nil {
+		// Explicit marker already set ExternalDocs — warn about redundant link defs
+		ctx.pkg.AddError(loader.ErrFromNode(
+			fmt.Errorf("kubebuilder:externalDoc marker is set, but doc comment also contains link definitions; marker takes precedence (found: %s)",
+				formatLinkDefs()),
+			node,
+		))
+		return
+	}
+
+	if len(links) > 1 {
+		ctx.pkg.AddError(loader.ErrFromNode(
+			fmt.Errorf("doc comment contains multiple link definitions for externalDoc; using the first one (found: %s)",
+				formatLinkDefs()),
+			node,
+		))
+	}
+
+	props.ExternalDocs = &apiextensionsv1.ExternalDocumentation{
+		Description: links[0].Text,
+		URL:         links[0].URL,
+	}
+}
+
 // typeToSchema creates a schema for the given AST type.
 func typeToSchema(ctx *schemaContext, rawType ast.Expr) *apiextensionsv1.JSONSchemaProps {
 	var props *apiextensionsv1.JSONSchemaProps
@@ -238,6 +289,7 @@ func typeToSchema(ctx *schemaContext, rawType ast.Expr) *apiextensionsv1.JSONSch
 	props.Description = ctx.info.Doc
 
 	applyMarkers(ctx, ctx.info.Markers, props, rawType)
+	applyDocLinkDef(ctx, props, ctx.info.Doc, rawType)
 
 	return props
 }
@@ -528,6 +580,7 @@ func structToSchema(ctx *schemaContext, structType *ast.StructType) *apiextensio
 		propSchema.Description = field.Doc
 
 		applyMarkers(ctx, field.Markers, propSchema, field.RawField)
+		applyDocLinkDef(ctx, propSchema, field.Doc, field.RawField)
 
 		if inline {
 			props.AllOf = append(props.AllOf, *propSchema)

pkg/crd/schema.go

@@ -368,6 +368,14 @@ type CronJobSpec struct {
 	StringAliasWithAddedTitle StringAliasWithTitle `json:"stringAliasWithAddedTitle,omitempty"`
 	StringAliasWithTitle      StringAliasWithTitle `json:"stringAliasWithTitle,omitempty"`
 
+	// This tests that external documentation can be attached to a field.
+	// +kubebuilder:externalDoc:url="https://example.com/docs",description="external docs description"
+	FieldWithExternalDoc string `json:"fieldWithExternalDoc,omitempty"`
+
+	// This tests that external documentation can be attached with only url.
+	// +kubebuilder:externalDoc:url="https://example.com/docs"
+	FieldWithExternalDocURLOnly string `json:"fieldWithExternalDocURLOnly,omitempty"`
+
 	// This tests string slice validation.
 	// +kubebuilder:validation:MinItems=2
 	// +kubebuilder:validation:MaxItems=2

pkg/crd/testdata/cronjob_types.go

@@ -0,0 +1,87 @@
+/*
+
+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=v1
+package external_docs
+
+import (
+	metav1 "k8s.io/apimachinery/pkg/apis/meta/v1"
+)
+
+// +kubebuilder:object:root=true
+
+// ExternalDocSpec defines the desired state of ExternalDoc
+type ExternalDocSpec struct {
+	// This tests that external documentation can be attached to a field with url and description.
+	// +kubebuilder:externalDoc:url="https://example.com/docs",description="external docs description"
+	FieldWithExternalDoc string `json:"fieldWithExternalDoc,omitempty"`
+
+	// This tests that external documentation can be attached with only url.
+	// +kubebuilder:externalDoc:url="https://example.com/docs"
+	FieldWithExternalDocURLOnly string `json:"fieldWithExternalDocURLOnly,omitempty"`
+
+	// This tests that external documentation from a type is propagated.
+	TypeWithExternalDoc TypeWithExternalDoc `json:"typeWithExternalDoc,omitempty"`
+
+	// This field has a doc comment link definition.
+	//
+	// [Link Def Docs]: https://example.com/link-def
+	FieldWithLinkDef string `json:"fieldWithLinkDef,omitempty"`
+
+	// This field has multiple doc comment link definitions.
+	//
+	// [First Link]: https://example.com/first
+	// [Second Link]: https://example.com/second
+	FieldWithMultipleLinkDefs string `json:"fieldWithMultipleLinkDefs,omitempty"`
+
+	// This field has both a marker and a link definition.
+	//
+	// [Link Def Override]: https://example.com/link-def-override
+	// +kubebuilder:externalDoc:url="https://example.com/marker-wins",description="marker wins"
+	FieldWithMarkerAndLinkDef string `json:"fieldWithMarkerAndLinkDef,omitempty"`
+
+	// This field has no link definition, just a regular doc comment.
+	FieldWithNoLinkDef string `json:"fieldWithNoLinkDef,omitempty"`
+
+	// This tests that a type-level link definition propagates.
+	TypeWithLinkDef TypeWithLinkDef `json:"typeWithLinkDef,omitempty"`
+}
+
+// TypeWithExternalDoc is a type with external documentation.
+// +kubebuilder:externalDoc:url="https://example.com/type-docs",description="type-level external docs"
+type TypeWithExternalDoc string
+
+// TypeWithLinkDef is a type with a doc comment link definition.
+//
+// [Type Link Def]: https://example.com/type-link-def
+type TypeWithLinkDef string
+
+// ExternalDoc is the Schema for the external docs API
+type ExternalDoc struct {
+	metav1.TypeMeta   `json:",inline"`
+	metav1.ObjectMeta `json:"metadata,omitempty"`
+
+	Spec ExternalDocSpec `json:"spec,omitempty"`
+}
+
+// +kubebuilder:object:root=true
+
+// ExternalDocList contains a list of ExternalDoc
+type ExternalDocList struct {
+	metav1.TypeMeta `json:",inline"`
+	metav1.ListMeta `json:"metadata,omitempty"`
+	Items           []ExternalDoc `json:"items"`
+}

pkg/crd/testdata/external_docs/types.go

@@ -244,6 +244,19 @@ spec:
                   for local type declarations.
                 maxLength: 10
                 type: string
+              fieldWithExternalDoc:
+                description: This tests that external documentation can be attached
+                  to a field.
+                externalDocs:
+                  description: external docs description
+                  url: https://example.com/docs
+                type: string
+              fieldWithExternalDocURLOnly:
+                description: This tests that external documentation can be attached
+                  with only url.
+                externalDocs:
+                  url: https://example.com/docs
+                type: string
               float64WithValidations:
                 maximum: 1.5
                 minimum: -0.5