Added support for 3.2 tags

Author: BlakeTheAwesome

openapi/bootstrap.go

@@ -65,12 +65,27 @@ func createBootstrapTags() []*Tag {
 	return []*Tag{
 		{
 			Name:        "users",
+			Summary:     pointer.From("Users"),
 			Description: pointer.From("User management operations"),
+			Kind:        pointer.From("nav"),
 			ExternalDocs: &oas3.ExternalDocumentation{
 				Description: pointer.From("User API documentation"),
 				URL:         "https://docs.example.com/users",
 			},
 		},
+		{
+			Name:        "admin",
+			Summary:     pointer.From("Admin"),
+			Description: pointer.From("Administrative operations"),
+			Parent:      pointer.From("users"),
+			Kind:        pointer.From("nav"),
+		},
+		{
+			Name:        "beta-features",
+			Summary:     pointer.From("Beta"),
+			Description: pointer.From("Experimental features"),
+			Kind:        pointer.From("badge"),
+		},
 	}
 }
 

openapi/core/tag.go

@@ -10,7 +10,10 @@ type Tag struct {
 	marshaller.CoreModel `model:"tag"`
 
 	Name         marshaller.Node[string]                          `key:"name"`
+	Summary      marshaller.Node[*string]                         `key:"summary"`
 	Description  marshaller.Node[*string]                         `key:"description"`
 	ExternalDocs marshaller.Node[*oas3core.ExternalDocumentation] `key:"externalDocs"`
+	Parent       marshaller.Node[*string]                         `key:"parent"`
+	Kind         marshaller.Node[*string]                         `key:"kind"`
 	Extensions   core.Extensions                                  `key:"extensions"`
 }

openapi/tag.go

@@ -17,10 +17,16 @@ type Tag struct {
 
 	// The name of the tag.
 	Name string
+	// A short summary of the tag, used for display purposes.
+	Summary *string
 	// A description for the tag. May contain CommonMark syntax.
 	Description *string
 	// External documentation for this tag.
 	ExternalDocs *oas3.ExternalDocumentation
+	// The name of a tag that this tag is nested under. The named tag must exist in the API description.
+	Parent *string
+	// A machine-readable string to categorize what sort of tag it is.
+	Kind *string
 
 	// Extensions provides a list of extensions to the Tag object.
 	Extensions *extensions.Extensions
@@ -52,6 +58,30 @@ func (t *Tag) GetExternalDocs() *oas3.ExternalDocumentation {
 	return t.ExternalDocs
 }
 
+// GetSummary returns the value of the Summary field. Returns empty string if not set.
+func (t *Tag) GetSummary() string {
+	if t == nil || t.Summary == nil {
+		return ""
+	}
+	return *t.Summary
+}
+
+// GetParent returns the value of the Parent field. Returns empty string if not set.
+func (t *Tag) GetParent() string {
+	if t == nil || t.Parent == nil {
+		return ""
+	}
+	return *t.Parent
+}
+
+// GetKind returns the value of the Kind field. Returns empty string if not set.
+func (t *Tag) GetKind() string {
+	if t == nil || t.Kind == nil {
+		return ""
+	}
+	return *t.Kind
+}
+
 // GetExtensions returns the value of the Extensions field. Returns an empty extensions map if not set.
 func (t *Tag) GetExtensions() *extensions.Extensions {
 	if t == nil || t.Extensions == nil {
@@ -77,3 +107,61 @@ func (t *Tag) Validate(ctx context.Context, opts ...validation.Option) []error {
 
 	return errs
 }
+
+// ValidateWithTags validates the Tag object in the context of all tags to check for parent relationships.
+// This should be called during document-level validation where all tags are available.
+func (t *Tag) ValidateWithTags(ctx context.Context, allTags []*Tag, opts ...validation.Option) []error {
+	errs := t.Validate(ctx, opts...)
+
+	if t.Parent != nil && *t.Parent != "" {
+		// Check if parent tag exists
+		parentExists := false
+		for _, tag := range allTags {
+			if tag != nil && tag.Name == *t.Parent {
+				parentExists = true
+				break
+			}
+		}
+
+		if !parentExists {
+			core := t.GetCore()
+			errs = append(errs, validation.NewValueError(
+				validation.NewMissingValueError("parent tag '%s' does not exist", *t.Parent),
+				core, core.Parent))
+		}
+
+		// Check for circular references
+		if t.hasCircularParentReference(allTags, make(map[string]bool)) {
+			core := t.GetCore()
+			errs = append(errs, validation.NewValueError(
+				validation.NewValueValidationError("circular parent reference detected for tag '%s'", t.Name),
+				core, core.Parent))
+		}
+	}
+
+	return errs
+}
+
+// hasCircularParentReference checks if this tag has a circular parent reference
+func (t *Tag) hasCircularParentReference(allTags []*Tag, visited map[string]bool) bool {
+	if t == nil || t.Parent == nil || *t.Parent == "" {
+		return false
+	}
+
+	// If we've already visited this tag, we have a circular reference
+	if visited[t.Name] {
+		return true
+	}
+
+	// Mark this tag as visited
+	visited[t.Name] = true
+
+	// Find the parent tag and recursively check
+	for _, tag := range allTags {
+		if tag != nil && tag.Name == *t.Parent {
+			return tag.hasCircularParentReference(allTags, visited)
+		}
+	}
+
+	return false
+}

openapi/tag_kind_registry.go

@@ -0,0 +1,57 @@
+package openapi
+
+// TagKind represents commonly used values for the Tag.Kind field.
+// These values are registered in the OpenAPI Initiative's Tag Kind Registry
+// at https://spec.openapis.org/registry/tag-kind/
+type TagKind string
+
+// Officially registered Tag Kind values from the OpenAPI Initiative registry
+const (
+	// TagKindNav represents tags used for navigation purposes
+	TagKindNav TagKind = "nav"
+
+	// TagKindBadge represents tags used for visible badges or labels
+	TagKindBadge TagKind = "badge"
+
+	// TagKindAudience represents tags that categorize operations by target audience
+	TagKindAudience TagKind = "audience"
+)
+
+// String returns the string representation of the TagKind
+func (tk TagKind) String() string {
+	return string(tk)
+}
+
+// IsRegistered checks if the TagKind value is one of the officially registered values
+func (tk TagKind) IsRegistered() bool {
+	switch tk {
+	case TagKindNav, TagKindBadge, TagKindAudience:
+		return true
+	default:
+		return false
+	}
+}
+
+// GetRegisteredTagKinds returns all officially registered tag kind values
+func GetRegisteredTagKinds() []TagKind {
+	return []TagKind{
+		TagKindNav,
+		TagKindBadge,
+		TagKindAudience,
+	}
+}
+
+// TagKindDescriptions provides human-readable descriptions for each registered tag kind
+var TagKindDescriptions = map[TagKind]string{
+	TagKindNav:      "Navigation - Used for structuring API documentation navigation",
+	TagKindBadge:    "Badge - Used for visible badges or labels in documentation",
+	TagKindAudience: "Audience - Used to categorize operations by target audience",
+}
+
+// GetTagKindDescription returns a human-readable description for a tag kind
+func GetTagKindDescription(kind TagKind) string {
+	if desc, exists := TagKindDescriptions[kind]; exists {
+		return desc
+	}
+	return "Custom tag kind - not in the official registry (any string value is allowed)"
+}

openapi/tag_unmarshal_test.go

@@ -39,3 +39,95 @@ x-test: some-value
 	require.True(t, ok)
 	require.Equal(t, "some-value", ext.Value)
 }
+
+func TestTag_Unmarshal_WithNewFields_Success(t *testing.T) {
+	t.Parallel()
+
+	yml := `
+name: products
+summary: Products
+description: All product-related operations
+parent: catalog
+kind: nav
+externalDocs:
+  description: Product API documentation
+  url: https://example.com/products
+x-custom: custom-value
+`
+
+	var tag openapi.Tag
+
+	validationErrs, err := marshaller.Unmarshal(t.Context(), bytes.NewBufferString(yml), &tag)
+	require.NoError(t, err)
+	require.Empty(t, validationErrs)
+
+	require.Equal(t, "products", tag.GetName())
+	require.Equal(t, "Products", tag.GetSummary())
+	require.Equal(t, "All product-related operations", tag.GetDescription())
+	require.Equal(t, "catalog", tag.GetParent())
+	require.Equal(t, "nav", tag.GetKind())
+
+	extDocs := tag.GetExternalDocs()
+	require.NotNil(t, extDocs)
+	require.Equal(t, "Product API documentation", extDocs.GetDescription())
+	require.Equal(t, "https://example.com/products", extDocs.GetURL())
+
+	ext, ok := tag.GetExtensions().Get("x-custom")
+	require.True(t, ok)
+	require.Equal(t, "custom-value", ext.Value)
+}
+
+func TestTag_Unmarshal_MinimalNewFields_Success(t *testing.T) {
+	t.Parallel()
+
+	yml := `
+name: minimal
+summary: Minimal Tag
+`
+
+	var tag openapi.Tag
+
+	validationErrs, err := marshaller.Unmarshal(t.Context(), bytes.NewBufferString(yml), &tag)
+	require.NoError(t, err)
+	require.Empty(t, validationErrs)
+
+	require.Equal(t, "minimal", tag.GetName())
+	require.Equal(t, "Minimal Tag", tag.GetSummary())
+	require.Equal(t, "", tag.GetDescription())
+	require.Equal(t, "", tag.GetParent())
+	require.Equal(t, "", tag.GetKind())
+}
+
+func TestTag_Unmarshal_KindValues_Success(t *testing.T) {
+	t.Parallel()
+
+	tests := []struct {
+		name     string
+		kind     string
+		expected string
+	}{
+		{"nav kind", "nav", "nav"},
+		{"badge kind", "badge", "badge"},
+		{"audience kind", "audience", "audience"},
+		{"custom kind", "custom-value", "custom-value"},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			t.Parallel()
+
+			yml := `
+name: test
+kind: ` + tt.kind
+
+			var tag openapi.Tag
+
+			validationErrs, err := marshaller.Unmarshal(t.Context(), bytes.NewBufferString(yml), &tag)
+			require.NoError(t, err)
+			require.Empty(t, validationErrs)
+
+			require.Equal(t, "test", tag.GetName())
+			require.Equal(t, tt.expected, tag.GetKind())
+		})
+	}
+}