feat(openapi3conv): generalize API to any 3.x target version

Renames UpgradeTo31 to Upgrade and lifts the target version into the
options struct, so callers can target 3.1, 3.2, or any future 3.x where
representational rewrites can land in this package. UpgradeTo31 stays as
a convenience wrapper.

OpenAPI 3.2 introduced no breaking changes over 3.1 (purely additive:
structured tags, streaming media types, additionalOperations, OAuth
device flow, defaultMapping in discriminator). So 3.1 -> 3.2 is just a
version-string change with no rewrites; the existing 3.0 -> 3.1
canonicalization is sufficient to reach a clean 3.2 form.

Cross-major upgrades (3 -> 4 if/when v4 ships) are explicitly rejected
with an error pointing at the openapi2conv pattern as the right home for
that work. Same for downgrades and unparseable version strings.

New tests cover:
- TestUpgrade_CustomTarget — non-default 3.1.0
- TestUpgrade_TargetIs32 — 3.0 input, 3.2 target, rewrites still applied
- TestUpgrade_SkipVersionBump — leaves doc.OpenAPI alone
- TestUpgrade_RejectsCrossMajor — 4.0.0 target errors clearly
- TestUpgrade_RejectsDowngrade — 3.1 -> 3.0 errors
- TestUpgrade_RejectsInvalidVersion — non-semver target errors

Updates package doc to spell out the in-scope/out-of-scope boundary
(3.x ↔ 3.x in scope; cross-major out of scope; downgrades out of scope).

Author: reuvenharrison

openapi3conv/doc.go

@@ -1,12 +1,20 @@
-// Package openapi3conv canonicalizes an OpenAPI 3.0 document into the OpenAPI 3.1
-// representation. Schema-level constructs serialize differently between the two
-// versions but represent the same semantics; this package rewrites the 3.0 forms
-// into their 3.1 equivalents in place. The transformation is mechanical and
-// lossless — every 3.0 construct has a direct 3.1 form.
+// Package openapi3conv canonicalizes an OpenAPI 3.x document into the
+// representation of a chosen target version. Schema-level constructs serialize
+// differently between OpenAPI 3.0 and 3.1, but represent the same semantics;
+// this package rewrites the 3.0 forms into their 3.1 equivalents in place.
+// The transformation is mechanical and lossless — every 3.0 construct has a
+// direct 3.1 form. OpenAPI 3.2 is purely additive over 3.1, so 3.1 → 3.2 is
+// a version-string change with no further rewrites.
 //
-// Use this when a downstream consumer (diff tools, validators, code generators)
-// needs a single canonical representation regardless of the source spec's
-// declared version.
+// Use this when a downstream consumer (diff tools, validators, code
+// generators) needs a single canonical representation regardless of the
+// source spec's declared version.
 //
-// The opposite direction (3.1 → 3.0) is lossy by nature and out of scope.
+// Scope:
+//   - In scope: 3.0 ↔ 3.1 ↔ 3.2 ↔ any future 3.x where representational
+//     differences are rewritable in place.
+//   - Out of scope: 3.x → 3.0 (lossy by nature).
+//   - Out of scope: cross-major upgrades (3 → 4 if/when v4 ships). Those
+//     belong in a dedicated package mirroring openapi2conv (which converts
+//     Swagger 2.0 documents to OpenAPI 3.0).
 package openapi3conv

openapi3conv/openapi3_conv.go

@@ -3,66 +3,95 @@ package openapi3conv
 import (
 	"fmt"
 	"io"
+	"strconv"
+	"strings"
 
 	"github.com/getkin/kin-openapi/openapi3"
 )
 
 // DefaultTargetVersion is the OpenAPI version string written when bumping the
-// document version. Set to the current 3.1 patch release; the OAI upgrade
-// guide uses the same.
+// document version. The OAI upgrade guide uses the current 3.1 patch release.
 const DefaultTargetVersion = "3.1.1"
 
 // UpgradeOptions controls per-pass behaviour.
 type UpgradeOptions struct {
+	// Target is the version string written when SkipVersionBump is false.
+	// Defaults to DefaultTargetVersion. Currently any 3.x version is accepted;
+	// representational rewrites only exist for 3.0 → 3.1, since 3.1 → 3.2 is
+	// purely additive (no breaking changes). Future minor versions that
+	// introduce representational changes can extend the dispatch in Upgrade.
+	Target string
+
 	// SkipVersionBump leaves doc.OpenAPI unchanged. Useful for consumers
 	// that want representations canonicalized while preserving the stated
 	// version (e.g., a pre-diff normalization step).
 	SkipVersionBump bool
 
-	// TargetVersion is the version string written when SkipVersionBump is
-	// false. Defaults to DefaultTargetVersion.
-	TargetVersion string
-
 	// Verbose, if non-nil, receives one line per rewrite for debugging.
 	Verbose io.Writer
 }
 
-// UpgradeTo31 rewrites every 3.0-form construct in doc into its 3.1 form
-// in place: bumps the version, replaces nullable: true with type arrays,
-// replaces boolean exclusiveMinimum/exclusiveMaximum with numeric form,
-// replaces example with examples. Idempotent on already-3.1 documents.
+// Upgrade canonicalizes doc into the representation of opts.Target in place.
 //
-// Returns an error only if the document is structurally invalid (e.g., nil
-// document).
-func UpgradeTo31(doc *openapi3.T) error {
-	return UpgradeTo31WithOptions(doc, UpgradeOptions{})
-}
-
-// UpgradeTo31WithOptions is the variant with explicit options.
-func UpgradeTo31WithOptions(doc *openapi3.T, opts UpgradeOptions) error {
+// The schema-level rewrites the walker applies (nullable → type array, boolean
+// exclusive bounds → numeric, example → examples) are idempotent and
+// convergent on the 3.1+ form. Calling Upgrade on an already-3.1 (or 3.2)
+// document is a no-op aside from the version bump.
+//
+// Cross-major upgrades are not supported. OpenAPI 4 (or any future major
+// version) will require a separate package mirroring the openapi2conv
+// pattern (which converts Swagger 2.0 documents to OpenAPI 3.0). Returning
+// an error here keeps that boundary explicit.
+func Upgrade(doc *openapi3.T, opts UpgradeOptions) error {
 	if doc == nil {
 		return fmt.Errorf("openapi3conv: doc is nil")
 	}
 
-	target := opts.TargetVersion
+	target := opts.Target
 	if target == "" {
 		target = DefaultTargetVersion
 	}
 
+	srcMajor, srcMinor, err := parseVersion(doc.OpenAPI)
+	if err != nil {
+		return fmt.Errorf("openapi3conv: invalid doc.OpenAPI %q: %w", doc.OpenAPI, err)
+	}
+	tgtMajor, tgtMinor, err := parseVersion(target)
+	if err != nil {
+		return fmt.Errorf("openapi3conv: invalid Target %q: %w", target, err)
+	}
+
+	if srcMajor != tgtMajor {
+		return fmt.Errorf(
+			"openapi3conv: cross-major upgrade not supported (%s -> %s); "+
+				"a separate package is the right home for cross-major conversions "+
+				"(see openapi2conv for the existing 2 -> 3 pattern)",
+			doc.OpenAPI, target,
+		)
+	}
+	if tgtMinor < srcMinor {
+		return fmt.Errorf("openapi3conv: cannot downgrade %s to %s", doc.OpenAPI, target)
+	}
+
 	w := &walker{
 		visited: map[*openapi3.Schema]struct{}{},
 		opts:    opts,
 	}
+	w.walkDoc(doc)
 
 	if !opts.SkipVersionBump && doc.OpenAPI != target {
 		w.logf("openapi: %s -> %s", doc.OpenAPI, target)
 		doc.OpenAPI = target
 	}
-
-	w.walkDoc(doc)
 	return nil
 }
 
+// UpgradeTo31 is a convenience wrapper for Upgrade with Target = "3.1.1".
+// Idempotent on already-3.1 documents.
+func UpgradeTo31(doc *openapi3.T) error {
+	return Upgrade(doc, UpgradeOptions{})
+}
+
 // UpgradeSchema canonicalizes a single schema (and its descendants) in place.
 // Exposed for callers that need to upgrade a sub-tree rather than a full
 // document — e.g., a diff tool comparing isolated schemas.
@@ -74,6 +103,24 @@ func UpgradeSchema(s *openapi3.Schema) {
 	w.walkSchema(s)
 }
 
+// parseVersion splits an OpenAPI version string ("3.0.3", "3.1.1", "3.2.0")
+// into major and minor integers. Patch and pre-release suffixes are ignored.
+func parseVersion(v string) (major, minor int, err error) {
+	parts := strings.SplitN(v, ".", 3)
+	if len(parts) < 2 {
+		return 0, 0, fmt.Errorf("expected MAJOR.MINOR[.PATCH], got %q", v)
+	}
+	major, err = strconv.Atoi(parts[0])
+	if err != nil {
+		return 0, 0, fmt.Errorf("invalid major %q: %w", parts[0], err)
+	}
+	minor, err = strconv.Atoi(parts[1])
+	if err != nil {
+		return 0, 0, fmt.Errorf("invalid minor %q: %w", parts[1], err)
+	}
+	return major, minor, nil
+}
+
 // walker carries cycle-tracking state and verbose output across the schema
 // graph. Each *Schema is visited at most once.
 type walker struct {

openapi3conv/openapi3_conv_test.go

@@ -48,30 +48,86 @@ paths: {}
 	assert.Equal(t, "3.1.1", doc.OpenAPI)
 }
 
-func TestUpgradeTo31_CustomTargetVersion(t *testing.T) {
+func TestUpgrade_CustomTarget(t *testing.T) {
 	doc := loadV30(t, `
 openapi: 3.0.3
 info: {title: t, version: '1'}
 paths: {}
 `)
-	require.NoError(t, openapi3conv.UpgradeTo31WithOptions(doc, openapi3conv.UpgradeOptions{
-		TargetVersion: "3.1.0",
+	require.NoError(t, openapi3conv.Upgrade(doc, openapi3conv.UpgradeOptions{
+		Target: "3.1.0",
 	}))
 	assert.Equal(t, "3.1.0", doc.OpenAPI)
 }
 
-func TestUpgradeTo31_SkipVersionBump(t *testing.T) {
+func TestUpgrade_TargetIs32(t *testing.T) {
+	// 3.2 is purely additive over 3.1 — no schema-level rewrites between
+	// them. Upgrade applies the 3.0 → 3.1 rewrites and writes the 3.2
+	// version string. The resulting doc is canonical and version-correct.
 	doc := loadV30(t, `
 openapi: 3.0.3
 info: {title: t, version: '1'}
 paths: {}
+components:
+  schemas:
+    Pet:
+      type: string
+      nullable: true
 `)
-	require.NoError(t, openapi3conv.UpgradeTo31WithOptions(doc, openapi3conv.UpgradeOptions{
+	require.NoError(t, openapi3conv.Upgrade(doc, openapi3conv.UpgradeOptions{
+		Target: "3.2.0",
+	}))
+	assert.Equal(t, "3.2.0", doc.OpenAPI)
+	assert.Equal(t, openapi3.Types{"string", "null"}, *doc.Components.Schemas["Pet"].Value.Type)
+}
+
+func TestUpgrade_SkipVersionBump(t *testing.T) {
+	doc := loadV30(t, `
+openapi: 3.0.3
+info: {title: t, version: '1'}
+paths: {}
+`)
+	require.NoError(t, openapi3conv.Upgrade(doc, openapi3conv.UpgradeOptions{
 		SkipVersionBump: true,
 	}))
 	assert.Equal(t, "3.0.3", doc.OpenAPI)
 }
 
+func TestUpgrade_RejectsCrossMajor(t *testing.T) {
+	// Cross-major upgrades belong in a dedicated package (mirror of
+	// openapi2conv). Pre-pin that boundary with an explicit error so any
+	// future 3 → 4 transition lands somewhere predictable.
+	doc := loadV30(t, `
+openapi: 3.0.3
+info: {title: t, version: '1'}
+paths: {}
+`)
+	err := openapi3conv.Upgrade(doc, openapi3conv.UpgradeOptions{Target: "4.0.0"})
+	require.Error(t, err)
+	assert.Contains(t, err.Error(), "cross-major")
+}
+
+func TestUpgrade_RejectsDowngrade(t *testing.T) {
+	doc := loadV30(t, `
+openapi: 3.1.1
+info: {title: t, version: '1'}
+paths: {}
+`)
+	err := openapi3conv.Upgrade(doc, openapi3conv.UpgradeOptions{Target: "3.0.3"})
+	require.Error(t, err)
+	assert.Contains(t, err.Error(), "downgrade")
+}
+
+func TestUpgrade_RejectsInvalidVersion(t *testing.T) {
+	doc := loadV30(t, `
+openapi: 3.0.3
+info: {title: t, version: '1'}
+paths: {}
+`)
+	err := openapi3conv.Upgrade(doc, openapi3conv.UpgradeOptions{Target: "not-a-version"})
+	require.Error(t, err)
+}
+
 // ---------------------------------------------------------------------------
 // Nullable rewrite
 // ---------------------------------------------------------------------------
@@ -400,7 +456,7 @@ func TestUpgradeTo31_CycleSafe(t *testing.T) {
 // Verbose logging
 // ---------------------------------------------------------------------------
 
-func TestUpgradeTo31_VerboseLogsRewrites(t *testing.T) {
+func TestUpgrade_VerboseLogsRewrites(t *testing.T) {
 	doc := loadV30(t, `
 openapi: 3.0.3
 info: {title: t, version: '1'}
@@ -413,7 +469,7 @@ components:
       example: fido
 `)
 	var buf bytes.Buffer
-	require.NoError(t, openapi3conv.UpgradeTo31WithOptions(doc, openapi3conv.UpgradeOptions{
+	require.NoError(t, openapi3conv.Upgrade(doc, openapi3conv.UpgradeOptions{
 		Verbose: &buf,
 	}))
 	out := buf.String()