OCM-17280 | feat: Add support for deprecated annotation

pkg/annotations/annotations.go

@@ -64,6 +64,12 @@ func GoName(concept concepts.Annotated) string {
 	return fmt.Sprintf("%s", name)
 }
 
+// IsDeprecated checks if the given concept has a `deprecated` annotation.
+func IsDeprecated(concept concepts.Annotated) bool {
+	annotation := concept.GetAnnotation("deprecated")
+	return annotation != nil
+}
+
 // Reference checks if the given concept has a `reference` annotation. If it has it then it returns the value
 // of the `path` parameter. It returns an empty string if there is no such annotation or parameter.
 func ReferencePath(concept concepts.Annotated) string {

pkg/annotations/annotations_test.go

@@ -0,0 +1,196 @@
+/*
+Copyright (c) 2025 Red Hat, Inc.
+
+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 annotations
+
+import (
+	. "github.com/onsi/ginkgo/v2"
+	. "github.com/onsi/gomega"
+	"github.com/openshift-online/ocm-api-metamodel/pkg/concepts"
+	"github.com/openshift-online/ocm-api-metamodel/pkg/names"
+)
+
+var _ = Describe("Deprecation annotation support", func() {
+	Describe("IsDeprecated function", func() {
+		var annotatedConcept concepts.Annotated
+
+		BeforeEach(func() {
+			// Create a test type that implements concepts.Annotated
+			annotatedConcept = concepts.NewType()
+		})
+
+		Context("when concept has deprecated annotation", func() {
+			It("should return true for deprecated annotation without parameters", func() {
+				// Create and add deprecated annotation
+				deprecatedAnnotation := concepts.NewAnnotation()
+				deprecatedAnnotation.SetName("deprecated")
+				annotatedConcept.AddAnnotation(deprecatedAnnotation)
+
+				// Test IsDeprecated function
+				result := IsDeprecated(annotatedConcept)
+				Expect(result).To(BeTrue())
+			})
+
+			It("should return true for deprecated annotation with parameters", func() {
+				// Create deprecated annotation with parameters
+				deprecatedAnnotation := concepts.NewAnnotation()
+				deprecatedAnnotation.SetName("deprecated")
+
+				// Add a parameter (like a deprecation message)
+				deprecatedAnnotation.AddParameter("message", "This feature will be removed in v2")
+
+				annotatedConcept.AddAnnotation(deprecatedAnnotation)
+
+				// Test IsDeprecated function
+				result := IsDeprecated(annotatedConcept)
+				Expect(result).To(BeTrue())
+			})
+
+			It("should return true when deprecated annotation exists among multiple annotations", func() {
+				// Add multiple annotations including deprecated
+				jsonAnnotation := concepts.NewAnnotation()
+				jsonAnnotation.SetName("json")
+				annotatedConcept.AddAnnotation(jsonAnnotation)
+
+				deprecatedAnnotation := concepts.NewAnnotation()
+				deprecatedAnnotation.SetName("deprecated")
+				annotatedConcept.AddAnnotation(deprecatedAnnotation)
+
+				httpAnnotation := concepts.NewAnnotation()
+				httpAnnotation.SetName("http")
+				annotatedConcept.AddAnnotation(httpAnnotation)
+
+				// Test IsDeprecated function
+				result := IsDeprecated(annotatedConcept)
+				Expect(result).To(BeTrue())
+			})
+		})
+
+		Context("when concept does not have deprecated annotation", func() {
+			It("should return false for concept with no annotations", func() {
+				// Test IsDeprecated function on clean concept
+				result := IsDeprecated(annotatedConcept)
+				Expect(result).To(BeFalse())
+			})
+
+			It("should return false for concept with other annotations but no deprecated", func() {
+				// Add non-deprecated annotations
+				jsonAnnotation := concepts.NewAnnotation()
+				jsonAnnotation.SetName("json")
+				annotatedConcept.AddAnnotation(jsonAnnotation)
+
+				httpAnnotation := concepts.NewAnnotation()
+				httpAnnotation.SetName("http")
+				annotatedConcept.AddAnnotation(httpAnnotation)
+
+				goAnnotation := concepts.NewAnnotation()
+				goAnnotation.SetName("go")
+				annotatedConcept.AddAnnotation(goAnnotation)
+
+				// Test IsDeprecated function
+				result := IsDeprecated(annotatedConcept)
+				Expect(result).To(BeFalse())
+			})
+
+			It("should return false for annotation with similar but different name", func() {
+				// Add annotation with similar name
+				similarAnnotation := concepts.NewAnnotation()
+				similarAnnotation.SetName("deprecation") // Note: not "deprecated"
+				annotatedConcept.AddAnnotation(similarAnnotation)
+
+				// Test IsDeprecated function
+				result := IsDeprecated(annotatedConcept)
+				Expect(result).To(BeFalse())
+			})
+		})
+
+		Context("edge cases", func() {
+			It("should handle case-sensitive annotation name correctly", func() {
+				// Add annotation with different case
+				upperCaseAnnotation := concepts.NewAnnotation()
+				upperCaseAnnotation.SetName("DEPRECATED") // Wrong case
+				annotatedConcept.AddAnnotation(upperCaseAnnotation)
+
+				// Test IsDeprecated function
+				result := IsDeprecated(annotatedConcept)
+				Expect(result).To(BeFalse())
+			})
+
+			It("should handle empty annotation name", func() {
+				// Add annotation with empty name
+				emptyAnnotation := concepts.NewAnnotation()
+				emptyAnnotation.SetName("")
+				annotatedConcept.AddAnnotation(emptyAnnotation)
+
+				// Test IsDeprecated function
+				result := IsDeprecated(annotatedConcept)
+				Expect(result).To(BeFalse())
+			})
+		})
+	})
+
+	Describe("Integration with different concept types", func() {
+		Context("when used with different annotated concepts", func() {
+			It("should work correctly with Attribute", func() {
+				attribute := concepts.NewAttribute()
+				attribute.SetName(names.ParseUsingCase("testAttribute"))
+
+				deprecatedAnnotation := concepts.NewAnnotation()
+				deprecatedAnnotation.SetName("deprecated")
+				attribute.AddAnnotation(deprecatedAnnotation)
+
+				result := IsDeprecated(attribute)
+				Expect(result).To(BeTrue())
+			})
+
+			It("should work correctly with Method", func() {
+				method := concepts.NewMethod()
+				method.SetName(names.ParseUsingCase("testMethod"))
+
+				deprecatedAnnotation := concepts.NewAnnotation()
+				deprecatedAnnotation.SetName("deprecated")
+				method.AddAnnotation(deprecatedAnnotation)
+
+				result := IsDeprecated(method)
+				Expect(result).To(BeTrue())
+			})
+
+			It("should work correctly with Resource", func() {
+				resource := concepts.NewResource()
+				resource.SetName(names.ParseUsingCase("testResource"))
+
+				deprecatedAnnotation := concepts.NewAnnotation()
+				deprecatedAnnotation.SetName("deprecated")
+				resource.AddAnnotation(deprecatedAnnotation)
+
+				result := IsDeprecated(resource)
+				Expect(result).To(BeTrue())
+			})
+
+			It("should work correctly with Parameter", func() {
+				parameter := concepts.NewParameter()
+				parameter.SetName(names.ParseUsingCase("testParameter"))
+
+				deprecatedAnnotation := concepts.NewAnnotation()
+				deprecatedAnnotation.SetName("deprecated")
+				parameter.AddAnnotation(deprecatedAnnotation)
+
+				result := IsDeprecated(parameter)
+				Expect(result).To(BeTrue())
+			})
+		})
+	})
+})

pkg/annotations/main_test.go

@@ -0,0 +1,31 @@
+/*
+Copyright (c) 2025 Red Hat, Inc.
+
+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.
+*/
+
+// This file contains the definition of the test suite.
+
+package annotations
+
+import (
+	"testing"
+
+	. "github.com/onsi/ginkgo/v2"
+	. "github.com/onsi/gomega"
+)
+
+func TestAnnotations(t *testing.T) {
+	RegisterFailHandler(Fail)
+	RunSpecs(t, "Annotations")
+}

pkg/generators/openapi/openapi_generator.go

@@ -22,6 +22,7 @@ import (
 	"sort"
 	"strings"
 
+	"github.com/openshift-online/ocm-api-metamodel/pkg/annotations"
 	"github.com/openshift-online/ocm-api-metamodel/pkg/concepts"
 	"github.com/openshift-online/ocm-api-metamodel/pkg/http"
 	"github.com/openshift-online/ocm-api-metamodel/pkg/reporter"
@@ -233,12 +234,12 @@ func (g *OpenAPIGenerator) generatePaths(version *concepts.Version) {
 	// Generate the specification:
 	g.buffer.StartObject("paths")
 
-	// Add the metadata path:
-	g.generateMetadataPath(version)
-
 	// Add the path for the root resource:
 	empty := []*concepts.Locator{}
 	root := g.absolutePath(version, empty)
+
+	g.generateMetadataPath(version)
+
 	g.generateResourcePaths(root, empty, version.Root())
 
 	// Add the paths for the rest of the resources:
@@ -315,6 +316,10 @@ func (g *OpenAPIGenerator) generateResourcePaths(prefix string,
 func (g *OpenAPIGenerator) generateMethod(path []*concepts.Locator, method *concepts.Method) {
 	g.buffer.StartObject(strings.ToLower(g.binding.Method(method)))
 	g.generateDescription(method.Doc())
+	// Mark as deprecated if either the method or its parent resource is deprecated
+	if annotations.IsDeprecated(method) || annotations.IsDeprecated(method.Owner()) {
+		g.buffer.Field("deprecated", true)
+	}
 	g.generateURLParameters(path, method)
 	parameters := g.binding.RequestBodyParameters(method)
 	if len(parameters) > 0 {
@@ -381,6 +386,9 @@ func (g *OpenAPIGenerator) generateQueryParameter(parameter *concepts.Parameter)
 	g.buffer.Field("name", g.binding.QueryParameterName(parameter))
 	g.generateDescription(parameter.Doc())
 	g.buffer.Field("in", "query")
+	if annotations.IsDeprecated(parameter) {
+		g.buffer.Field("deprecated", true)
+	}
 	g.buffer.StartObject("schema")
 	g.generateSchemaReference(parameter.Type())
 	g.buffer.EndObject()
@@ -428,6 +436,9 @@ func (g *OpenAPIGenerator) genrateParameterProperty(parameter *concepts.Paramete
 	name := g.names.ParameterPropertyName(parameter)
 	g.buffer.StartObject(name)
 	g.generateDescription(parameter.Doc())
+	if annotations.IsDeprecated(parameter) {
+		g.buffer.Field("deprecated", true)
+	}
 	g.generateSchemaReference(parameter.Type())
 	g.buffer.EndObject()
 }
@@ -484,6 +495,9 @@ func (g *OpenAPIGenerator) generateEnumSchema(typ *concepts.Type) {
 	name := g.names.SchemaName(typ)
 	g.buffer.StartObject(name)
 	g.generateDescription(typ.Doc())
+	if annotations.IsDeprecated(typ) {
+		g.buffer.Field("deprecated", true)
+	}
 	g.buffer.Field("type", "string")
 	g.buffer.StartArray("enum")
 	for _, value := range typ.Values() {
@@ -497,6 +511,9 @@ func (g *OpenAPIGenerator) generateStructSchema(typ *concepts.Type) {
 	name := g.names.SchemaName(typ)
 	g.buffer.StartObject(name)
 	g.generateDescription(typ.Doc())
+	if annotations.IsDeprecated(typ) {
+		g.buffer.Field("deprecated", true)
+	}
 	g.buffer.StartObject("properties")
 	if typ.IsClass() {
 		// Kind:
@@ -532,6 +549,9 @@ func (g *OpenAPIGenerator) generateStructProperty(attribute *concepts.Attribute)
 	name := g.names.AttributePropertyName(attribute)
 	g.buffer.StartObject(name)
 	g.generateDescription(attribute.Doc())
+	if annotations.IsDeprecated(attribute) {
+		g.buffer.Field("deprecated", true)
+	}
 	g.generateSchemaReference(attribute.Type())
 	g.buffer.EndObject()
 }