feat: annotate operations with stability level (#379)

* feat: annotate operations with stability level

internal/simplebuild/build.go

@@ -331,12 +331,15 @@ func (vs VersionSet) Annotate() {
 
 	for idx, op := range vs {
 		if op.Operation.Extensions == nil {
-			op.Operation.Extensions = make(map[string]interface{}, 6)
+			op.Operation.Extensions = make(map[string]interface{}, 8)
 		}
 		op.Operation.Extensions[vervet.ExtSnykApiResource] = op.ResourceName
 		op.Operation.Extensions[vervet.ExtSnykApiVersion] = op.Version.String()
 		op.Operation.Extensions[vervet.ExtSnykApiReleases] = releases
 		op.Operation.Extensions[vervet.ExtSnykApiLifecycle] = op.Version.LifecycleAt(time.Time{}).String()
+		op.Operation.Extensions[vervet.ExtApiStabilityLevel] = op.Version.Stability.String()
+		op.Operation.Extensions[vervet.ExtSnykApiStability] = op.Version.Stability.String()
+
 		if idx < (count - 1) {
 			laterVersion := vs[idx+1].Version
 			// Sanity check the later version actually deprecates this one

internal/simplebuild/build_test.go

@@ -501,6 +501,10 @@ func TestAnnotate(t *testing.T) {
 		c.Assert(vs[1].Operation.Extensions[vervet.ExtSnykApiResource], qt.Equals, "foo")
 		c.Assert(vs[2].Operation.Extensions[vervet.ExtSnykApiVersion], qt.Equals, "2024-03-01")
 		c.Assert(vs[2].Operation.Extensions[vervet.ExtSnykApiResource], qt.Equals, "bar")
+
+		// Check stability level for beta version
+		c.Assert(vs[1].Operation.Extensions[vervet.ExtApiStabilityLevel], qt.Equals, "beta")
+		c.Assert(vs[1].Operation.Extensions[vervet.ExtSnykApiStability], qt.Equals, "beta")
 	})
 
 	c.Run("adds a list of all other versions", func(c *qt.C) {
@@ -537,6 +541,9 @@ func TestAnnotate(t *testing.T) {
 			qt.DeepEquals,
 			[]string{"2024-01-01", "2024-02-01~beta", "2024-03-01"},
 		)
+
+		c.Assert(vs[1].Operation.Extensions[vervet.ExtApiStabilityLevel], qt.Equals, "beta")
+		c.Assert(vs[1].Operation.Extensions[vervet.ExtSnykApiStability], qt.Equals, "beta")
 	})
 
 	c.Run("adds deprecation annotations on older versions", func(c *qt.C) {
@@ -566,6 +573,9 @@ func TestAnnotate(t *testing.T) {
 		c.Assert(vs[1].Operation.Extensions[vervet.ExtSnykSunsetEligible], qt.Equals, "2024-08-29")
 		c.Assert(vs[2].Operation.Extensions[vervet.ExtSnykDeprecatedBy], qt.IsNil)
 		c.Assert(vs[2].Operation.Extensions[vervet.ExtSnykSunsetEligible], qt.IsNil)
+
+		c.Assert(vs[0].Operation.Extensions["x-stability-level"], qt.Equals, "beta")
+		c.Assert(vs[0].Operation.Extensions["x-snyk-api-stability"], qt.Equals, "beta")
 	})
 }
 

resource.go

@@ -21,6 +21,10 @@ const (
 	// spec with its API release stability level.
 	ExtSnykApiStability = "x-snyk-api-stability"
 
+	// ExtApiStability is used to annotate a path in a compiled OpenAPI spec
+	// with its API release stability level.
+	ExtApiStabilityLevel = "x-stability-level"
+
 	// ExtSnykApiLifecycle is used to annotate compiled OpenAPI with lifecycle
 	// stage: releases, deprecated or sunset. It is applied at the top-level as
 	// well as per-operation.