[Parsing] Allow OAS versions 3.1.2 and 3.2.0 (#840)

### Motivation

### Modifications

The OpenAPIKit dependency has been bumped to 3.9.0+ to use the new
version mapping feature.

The generator has been instructed to accept OAS documents of versions
3.1.2 and 3.2.0 in addition to the existing supported versions.

In order to parse OAS 3.2.0 without any of the features it adds,
OpenAPIKit has been instructed to parse OAS 3.2.0 as if it were OAS
3.1.2.

### Result

OpenAPI Documents versioned 3.1.2 and 3.2.0 will successfully load into
the generator.

### Test Plan

The test suite has been updated.

Author: mattpolzin

Package.swift

@@ -45,7 +45,7 @@ let package = Package(
         .package(url: "https://github.com/apple/swift-collections", from: "1.1.4"),
 
         // Read OpenAPI documents
-        .package(url: "https://github.com/mattpolzin/OpenAPIKit", from: "3.3.0"),
+        .package(url: "https://github.com/mattpolzin/OpenAPIKit", from: "3.9.0"),
         .package(url: "https://github.com/jpsim/Yams", "4.0.0"..<"7.0.0"),
 
         // CLI Tool
@@ -113,8 +113,10 @@ let package = Package(
             dependencies: [
                 "_OpenAPIGeneratorCore",
                 // Everything except windows: https://github.com/swiftlang/swift-package-manager/issues/6367
-                .target(name: "swift-openapi-generator", condition: .when(platforms: [.android, .linux, .macOS, .openbsd, .wasi, .custom("freebsd")])),
-                .product(name: "ArgumentParser", package: "swift-argument-parser"),
+                .target(
+                    name: "swift-openapi-generator",
+                    condition: .when(platforms: [.android, .linux, .macOS, .openbsd, .wasi, .custom("freebsd")])
+                ), .product(name: "ArgumentParser", package: "swift-argument-parser"),
             ],
             resources: [.copy("Resources")],
             swiftSettings: swiftSettings
@@ -162,5 +164,4 @@ for target in package.targets {
     case .macro, .plugin, .system, .binary: ()  // not applicable
     @unknown default: ()  // we don't know what to do here, do nothing
     }
-}
-// --- END: STANDARD CROSS-REPO SETTINGS DO NOT EDIT --- //
+}// --- END: STANDARD CROSS-REPO SETTINGS DO NOT EDIT --- //

README.md

@@ -17,7 +17,7 @@ The code is generated at build-time, so it's always in sync with the OpenAPI doc
 
 ## Features
 
-- Works with OpenAPI Specification versions 3.0 and 3.1.
+- Works with OpenAPI Specification versions 3.0 and 3.1 and has preliminary support for version 3.2.
 - Streaming request and response bodies enabling use cases such as JSON event streams, and large payloads without buffering.
 - Support for JSON, multipart, URL-encoded form, base64, plain text, and raw bytes, represented as value types with type-safe properties.
 - Client, server, and middleware abstractions, decoupling the generated code from the HTTP client library and web framework.
@@ -91,9 +91,9 @@ The Swift OpenAPI Generator project is split across multiple repositories to ena
 
 ## Requirements and supported features
 
-| Generator versions | Supported OpenAPI versions |
-| ------------------ | -------------------------- |
-| `1.0.0` ... `main` | 3.0, 3.1                   |
+| Generator versions | Supported OpenAPI versions  |
+| ------------------ | --------------------------- |
+| `1.0.0` ... `main` | 3.0, 3.1, 3.2 (preliminary) |
 
 See also [Supported OpenAPI features][supported-openapi-features].
 

Sources/_OpenAPIGeneratorCore/Parser/YamsParser.swift

@@ -54,6 +54,13 @@ public struct YamsParser: ParserProtocol {
         let decoder = YAMLDecoder()
         let openapiData = input.contents
 
+        let decodingOptions = [
+            DocumentConfiguration.versionMapKey: [
+                // Until we move to OpenAPIKit v5.0+ we will parse OAS 3.2.0 as if it were OAS 3.1.2
+                "3.2.0": OpenAPI.Document.Version.v3_1_2
+            ]
+        ]
+
         struct OpenAPIVersionedDocument: Decodable { var openapi: String? }
 
         let versionedDocument: OpenAPIVersionedDocument
@@ -73,7 +80,14 @@ public struct YamsParser: ParserProtocol {
             case "3.0.0", "3.0.1", "3.0.2", "3.0.3", "3.0.4":
                 let openAPI30Document = try decoder.decode(OpenAPIKit30.OpenAPI.Document.self, from: input.contents)
                 document = openAPI30Document.convert(to: .v3_1_0)
-            case "3.1.0", "3.1.1": document = try decoder.decode(OpenAPIKit.OpenAPI.Document.self, from: input.contents)
+            case "3.1.0", "3.1.1", "3.1.2":
+                document = try decoder.decode(OpenAPIKit.OpenAPI.Document.self, from: input.contents)
+            case "3.2.0":
+                document = try decoder.decode(
+                    OpenAPIKit.OpenAPI.Document.self,
+                    from: input.contents,
+                    userInfo: decodingOptions
+                )
             default:
                 throw Diagnostic.openAPIVersionError(
                     versionString: "openapi: \(openAPIVersion)",
@@ -128,7 +142,7 @@ extension Diagnostic {
     static func openAPIVersionError(versionString: String, location: Location) -> Diagnostic {
         error(
             message:
-                "Unsupported document version: \(versionString). Please provide a document with OpenAPI versions in the 3.0.x or 3.1.x sets.",
+                "Unsupported document version: \(versionString). Please provide a document with OpenAPI versions in the 3.0.x, 3.1.x, or 3.2.x sets.",
             location: location
         )
     }
@@ -139,7 +153,7 @@ extension Diagnostic {
     static func openAPIMissingVersionError(location: Location) -> Diagnostic {
         error(
             message:
-                "No key named openapi found. Please provide a valid OpenAPI document with OpenAPI versions in the 3.0.x or 3.1.x sets.",
+                "No key named openapi found. Please provide a valid OpenAPI document with OpenAPI versions in the 3.0.x, 3.1.x, or 3.2.x sets.",
             location: location
         )
     }

Sources/swift-openapi-generator/Documentation.docc/Swift-OpenAPI-Generator.md

@@ -16,7 +16,7 @@ The code is generated at build-time, so it's always in sync with the OpenAPI doc
 
 ## Features
 
-- Works with OpenAPI Specification versions 3.0 and 3.1.
+- Works with OpenAPI Specification versions 3.0 and 3.1 and has preliminary support for version 3.2.
 - Streaming request and response bodies enabling use cases such as JSON event streams, and large payloads without buffering.
 - Support for JSON, multipart, URL-encoded form, base64, plain text, and raw bytes, represented as value types with type-safe properties.
 - Client, server, and middleware abstractions, decoupling the generated code from the HTTP client library and web framework.
@@ -90,9 +90,9 @@ The Swift OpenAPI Generator project is split across multiple repositories to ena
 
 ### Requirements and supported features
 
-| Generator versions | Supported OpenAPI versions | Minimum Swift version |
-| ------------------ | -------------------------- | --------------------- |
-| `1.0.0` ... `main` | 3.0, 3.1                   | 5.9                   |
+| Generator versions | Supported OpenAPI versions  | Minimum Swift version |
+| ------------------ | --------------------------- | --------------------- |
+| `1.0.0` ... `main` | 3.0, 3.1, 3.2 (preliminary) | 5.9                   |
 
 See also <doc:Supported-OpenAPI-features>.
 

Tests/OpenAPIGeneratorCoreTests/Parser/Test_YamsParser.swift

@@ -24,13 +24,15 @@ final class Test_YamsParser: Test_Core {
         XCTAssertNoThrow(try _test(openAPIVersionString: "3.0.4"))
         XCTAssertNoThrow(try _test(openAPIVersionString: "3.1.0"))
         XCTAssertNoThrow(try _test(openAPIVersionString: "3.1.1"))
+        XCTAssertNoThrow(try _test(openAPIVersionString: "3.1.2"))
+        XCTAssertNoThrow(try _test(openAPIVersionString: "3.2.0"))
 
         let expected1 =
-            "/foo.yaml: error: Unsupported document version: openapi: 3.2.0. Please provide a document with OpenAPI versions in the 3.0.x or 3.1.x sets."
-        assertThrownError(try _test(openAPIVersionString: "3.2.0"), expectedDiagnostic: expected1)
+            "/foo.yaml: error: Unsupported document version: openapi: 3.3.0. Please provide a document with OpenAPI versions in the 3.0.x, 3.1.x, or 3.2.x sets."
+        assertThrownError(try _test(openAPIVersionString: "3.3.0"), expectedDiagnostic: expected1)
 
         let expected2 =
-            "/foo.yaml: error: Unsupported document version: openapi: 2.0. Please provide a document with OpenAPI versions in the 3.0.x or 3.1.x sets."
+            "/foo.yaml: error: Unsupported document version: openapi: 2.0. Please provide a document with OpenAPI versions in the 3.0.x, 3.1.x, or 3.2.x sets."
         assertThrownError(try _test(openAPIVersionString: "2.0"), expectedDiagnostic: expected2)
     }
 
@@ -56,7 +58,7 @@ final class Test_YamsParser: Test_Core {
             """
 
         let expected =
-            "/foo.yaml: error: No key named openapi found. Please provide a valid OpenAPI document with OpenAPI versions in the 3.0.x or 3.1.x sets."
+            "/foo.yaml: error: No key named openapi found. Please provide a valid OpenAPI document with OpenAPI versions in the 3.0.x, 3.1.x, or 3.2.x sets."
         assertThrownError(try _test(yaml), expectedDiagnostic: expected)
     }