Added upgrade path for 3.2 additionalOperations

Author: BlakeTheAwesome

openapi/testdata/upgrade/3_1_0_with_custom_methods.yaml

@@ -0,0 +1,54 @@
+openapi: 3.1.0
+info:
+  title: Test API with Custom Methods
+  version: 1.0.0
+  description: Test document with non-standard HTTP methods
+paths:
+  /test:
+    get:
+      summary: Standard GET operation
+      responses:
+        "200":
+          description: OK
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  message:
+                    type: string
+    copy:
+      summary: Custom COPY operation
+      responses:
+        "200":
+          description: Resource copied
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  success:
+                    type: boolean
+    move:
+      summary: Custom MOVE operation
+      responses:
+        "200":
+          description: Resource moved
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  newLocation:
+                    type: string
+  /another:
+    post:
+      summary: Standard POST operation
+      responses:
+        "201":
+          description: Created
+    purge:
+      summary: Custom PURGE operation
+      responses:
+        "204":
+          description: Purged

openapi/testdata/upgrade/expected_3_1_0_with_custom_methods_upgraded.yaml

@@ -0,0 +1,56 @@
+openapi: 3.2.0
+info:
+  title: Test API with Custom Methods
+  version: 1.0.0
+  description: Test document with non-standard HTTP methods
+paths:
+  /test:
+    get:
+      summary: Standard GET operation
+      responses:
+        "200":
+          description: OK
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  message:
+                    type: string
+    additionalOperations:
+      copy:
+        summary: Custom COPY operation
+        responses:
+          "200":
+            description: Resource copied
+            content:
+              application/json:
+                schema:
+                  type: object
+                  properties:
+                    success:
+                      type: boolean
+      move:
+        summary: Custom MOVE operation
+        responses:
+          "200":
+            description: Resource moved
+            content:
+              application/json:
+                schema:
+                  type: object
+                  properties:
+                    newLocation:
+                      type: string
+  /another:
+    post:
+      summary: Standard POST operation
+      responses:
+        "201":
+          description: Created
+    additionalOperations:
+      purge:
+        summary: Custom PURGE operation
+        responses:
+          "204":
+            description: Purged

openapi/upgrade.go

@@ -8,6 +8,7 @@ import (
 	"github.com/speakeasy-api/openapi/internal/version"
 	"github.com/speakeasy-api/openapi/jsonschema/oas3"
 	"github.com/speakeasy-api/openapi/marshaller"
+	"github.com/speakeasy-api/openapi/sequencedmap"
 	"gopkg.in/yaml.v3"
 )
 
@@ -112,12 +113,14 @@ func upgradeFrom310To312(_ context.Context, doc *OpenAPI, currentVersion *versio
 	doc.OpenAPI = maxVersion.String()
 }
 
-func upgradeFrom31To32(_ context.Context, doc *OpenAPI, currentVersion *version.Version, targetVersion *version.Version) {
+func upgradeFrom31To32(ctx context.Context, doc *OpenAPI, currentVersion *version.Version, targetVersion *version.Version) {
 	if !targetVersion.GreaterThan(*currentVersion) {
 		return
 	}
 
-	// TODO: Upgrade path additionalOperations for non-standard HTTP methods
+	// Upgrade path additionalOperations for non-standard HTTP methods
+	migrateAdditionalOperations31to32(ctx, doc)
+
 	// TODO: Upgrade tags such as x-displayName to summary, and x-tagGroups with parents, etc.
 
 	// Currently no breaking changes between 3.1.x and 3.2.x that need to be handled
@@ -131,6 +134,46 @@ func upgradeFrom31To32(_ context.Context, doc *OpenAPI, currentVersion *version.
 	doc.OpenAPI = maxVersion.String()
 }
 
+// migrateAdditionalOperations31to32 migrates non-standard HTTP methods from the main operations map
+// to the additionalOperations field in PathItem objects for OpenAPI 3.2.0+ compatibility.
+func migrateAdditionalOperations31to32(_ context.Context, doc *OpenAPI) {
+	if doc.Paths == nil {
+		return
+	}
+
+	for _, referencedPathItem := range doc.Paths.All() {
+		if referencedPathItem == nil || referencedPathItem.Object == nil {
+			continue
+		}
+
+		pathItem := referencedPathItem.Object
+		nonStandardMethods := sequencedmap.New[string, *Operation]()
+
+		// Find non-standard HTTP methods in the main operations map
+		for method, operation := range pathItem.All() {
+			if !IsStandardMethod(string(method)) {
+				nonStandardMethods.Set(string(method), operation)
+			}
+		}
+
+		// If we found non-standard methods, migrate them to additionalOperations
+		if nonStandardMethods.Len() > 0 {
+			// Initialize additionalOperations if it doesn't exist
+			if pathItem.AdditionalOperations == nil {
+				pathItem.AdditionalOperations = sequencedmap.New[string, *Operation]()
+			}
+
+			// Move each non-standard operation to additionalOperations
+			for method, operation := range nonStandardMethods.All() {
+				pathItem.AdditionalOperations.Set(method, operation)
+
+				// Remove from the main operations map
+				pathItem.Map.Delete(HTTPMethod(method))
+			}
+		}
+	}
+}
+
 func upgradeSchema30to31(js *oas3.JSONSchema[oas3.Referenceable]) {
 	if js == nil || js.IsReference() || js.IsRight() {
 		return

openapi/upgrade_test.go

@@ -57,6 +57,14 @@ func TestUpgrade_Success(t *testing.T) {
 			options:      nil,
 			description:  "nullable schema should upgrade to oneOf without panic",
 		},
+		{
+			name:          "upgrade_3_1_0_with_custom_methods",
+			inputFile:     "testdata/upgrade/3_1_0_with_custom_methods.yaml",
+			expectedFile:  "testdata/upgrade/expected_3_1_0_with_custom_methods_upgraded.yaml",
+			options:       []openapi.Option[openapi.UpgradeOptions]{openapi.WithUpgradeTargetVersion("3.2.0")},
+			description:   "3.1.0 with custom HTTP methods should migrate to additionalOperations",
+			targetVersion: "3.2.0",
+		},
 	}
 
 	for _, tt := range tests {
@@ -311,3 +319,75 @@ components:
 	assert.Nil(t, simpleExample.Example, "example should be nil")
 	assert.NotEmpty(t, simpleExample.Examples, "examples should not be empty")
 }
+
+func TestUpgradeAdditionalOperations(t *testing.T) {
+	t.Parallel()
+
+	ctx := t.Context()
+
+	// Create a document with non-standard HTTP methods
+	doc := &openapi.OpenAPI{
+		OpenAPI: "3.1.0",
+		Info: openapi.Info{
+			Title:   "Test API",
+			Version: "1.0.0",
+		},
+		Paths: openapi.NewPaths(),
+	}
+
+	// Add a path with both standard and non-standard methods
+	pathItem := openapi.NewPathItem()
+
+	// Standard method
+	pathItem.Set(openapi.HTTPMethodGet, &openapi.Operation{
+		Summary:   &[]string{"Get operation"}[0],
+		Responses: openapi.NewResponses(),
+	})
+
+	// Non-standard methods
+	pathItem.Set(openapi.HTTPMethod("copy"), &openapi.Operation{
+		Summary:   &[]string{"Copy operation"}[0],
+		Responses: openapi.NewResponses(),
+	})
+
+	pathItem.Set(openapi.HTTPMethod("purge"), &openapi.Operation{
+		Summary:   &[]string{"Purge operation"}[0],
+		Responses: openapi.NewResponses(),
+	})
+
+	doc.Paths.Set("/test", &openapi.ReferencedPathItem{Object: pathItem})
+
+	// Verify initial state
+	assert.Equal(t, 3, pathItem.Len(), "should have 3 operations initially")
+	assert.Nil(t, pathItem.AdditionalOperations, "additionalOperations should be nil initially")
+	assert.NotNil(t, pathItem.GetOperation(openapi.HTTPMethod("copy")), "copy operation should exist in main map")
+	assert.NotNil(t, pathItem.GetOperation(openapi.HTTPMethod("purge")), "purge operation should exist in main map")
+
+	// Perform upgrade to 3.2.0
+	upgraded, err := openapi.Upgrade(ctx, doc, openapi.WithUpgradeTargetVersion("3.2.0"))
+	require.NoError(t, err, "upgrade should not fail")
+	assert.True(t, upgraded, "upgrade should have been performed")
+	assert.Equal(t, "3.2.0", doc.OpenAPI, "version should be 3.2.0")
+
+	// Verify migration results
+	assert.Equal(t, 1, pathItem.Len(), "should have only 1 operation in main map after migration")
+	assert.NotNil(t, pathItem.AdditionalOperations, "additionalOperations should be initialized")
+	assert.Equal(t, 2, pathItem.AdditionalOperations.Len(), "should have 2 operations in additionalOperations")
+
+	// Verify standard method remains in main map
+	assert.NotNil(t, pathItem.GetOperation(openapi.HTTPMethodGet), "get operation should remain in main map")
+
+	// Verify non-standard methods are moved to additionalOperations
+	assert.Nil(t, pathItem.GetOperation(openapi.HTTPMethod("copy")), "copy operation should be removed from main map")
+	assert.Nil(t, pathItem.GetOperation(openapi.HTTPMethod("purge")), "purge operation should be removed from main map")
+
+	copyOp, exists := pathItem.AdditionalOperations.Get("copy")
+	assert.True(t, exists, "copy operation should exist in additionalOperations")
+	assert.NotNil(t, copyOp, "copy operation should not be nil")
+	assert.Equal(t, "Copy operation", *copyOp.Summary, "copy operation summary should be preserved")
+
+	purgeOp, exists := pathItem.AdditionalOperations.Get("purge")
+	assert.True(t, exists, "purge operation should exist in additionalOperations")
+	assert.NotNil(t, purgeOp, "purge operation should not be nil")
+	assert.Equal(t, "Purge operation", *purgeOp.Summary, "purge operation summary should be preserved")
+}