feat(openapi3conv): canonicalization pass for 3.0 -> 3.x (#1162)

Author: reuvenharrison

.github/docs/openapi3conv.txt

@@ -0,0 +1,59 @@
+package openapi3conv // import "github.com/getkin/kin-openapi/openapi3conv"
+
+Package openapi3conv canonicalizes an OpenAPI 3.x document into the latest 3.x
+representation in place. 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 and bumps the version string to the latest
+3.x patch release the package knows about.
+
+The OAI commits to strict compatibility for 3.x going forward (see the 3.2.1
+and 3.3.0 milestones), so a tool that handles the 3.1+ form correctly handles
+all later 3.x versions correctly too. The 3.0 → 3.1 transition — the only break
+in the 3.x line — is the gap this package exists to bridge. 3.1 → 3.2 (and any
+future 3.x) is purely additive and requires no rewrites; the package handles
+those as a version-string bump.
+
+Use this when a downstream consumer (diff tools, validators, code generators)
+needs a single canonical representation regardless of the source spec's declared
+version.
+
+Scope:
+  - In scope: 3.x → latest 3.x.
+  - Out of scope: any → 3.0 (downgrade is 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).
+
+Documents must be Validate()'d before calling Upgrade — passing an invalid
+document is undefined behaviour.
+
+FUNCTIONS
+
+func Upgrade(doc *openapi3.T, opts ...Option)
+    Upgrade canonicalizes doc into the latest 3.x representation in place.
+
+    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 later)
+    document is a no-op aside from the version string bump.
+
+    Cross-major upgrades (3 → 4 if/when v4 ships) are not handled here; that
+    belongs in a dedicated package mirroring the openapi2conv pattern.
+
+    doc must be Validate()'d before calling Upgrade; passing an invalid document
+    is undefined behaviour.
+
+func UpgradeSchema(s *openapi3.Schema)
+    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.
+
+
+TYPES
+
+type Option func(*upgradeOptions)
+    Option configures an Upgrade pass. See WithWriter.
+
+func WithWriter(w io.Writer) Option
+    WithWriter routes one debug line per applied rewrite to w.
+

openapi3conv/doc.go

@@ -0,0 +1,27 @@
+// Package openapi3conv canonicalizes an OpenAPI 3.x document into the latest
+// 3.x representation in place. 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 and bumps the version
+// string to the latest 3.x patch release the package knows about.
+//
+// The OAI commits to strict compatibility for 3.x going forward (see the
+// 3.2.1 and 3.3.0 milestones), so a tool that handles the 3.1+ form
+// correctly handles all later 3.x versions correctly too. The 3.0 → 3.1
+// transition — the only break in the 3.x line — is the gap this package
+// exists to bridge. 3.1 → 3.2 (and any future 3.x) is purely additive and
+// requires no rewrites; the package handles those as a version-string bump.
+//
+// Use this when a downstream consumer (diff tools, validators, code
+// generators) needs a single canonical representation regardless of the
+// source spec's declared version.
+//
+// Scope:
+//   - In scope: 3.x → latest 3.x.
+//   - Out of scope: any → 3.0 (downgrade is 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).
+//
+// Documents must be Validate()'d before calling Upgrade — passing an
+// invalid document is undefined behaviour.
+package openapi3conv