Support OpenAPI 3.1 in addition to 3.0 (#219)

Support OpenAPI 3.1 in addition to 3.0

### Motivation

Fixes #39. We need to start accepting 3.1 documents in addition to 3.0.

It also has useful features, like being able to add descriptions to references.

### Modifications

Migrated the codebase to use the `OpenAPIKit` instead of the `OpenAPIKit30` module, and updated the parser to handle both 3.0 and 3.1, and convert 3.0 to 3.1 documents in memory transparently.

### Result

OpenAPI 3.1 documents are now accepted, instead of rejected. Any 3.1 specific features can be addressed separately, this is the MVP support.

### Test Plan

Updated the file-based reference test to use version 3.1.0, and the parser tests that 3.0.x documents are loaded and converted successfully. So no need to duplicate our reference tests or anything.


Reviewed by: Kyle-Ye, glbrntt

Builds:
     ✔︎ pull request validation (5.8) - Build finished. 
     ✔︎ pull request validation (5.9) - Build finished. 
     ✔︎ pull request validation (docc test) - Build finished. 
     ✔︎ pull request validation (integration test) - Build finished. 
     ✔︎ pull request validation (nightly) - Build finished. 
     ✔︎ pull request validation (soundness) - Build finished. 

#219

Author: czechboy0

IntegrationTest/Sources/openapi.yaml

@@ -1,4 +1,4 @@
-openapi: "3.0.3"
+openapi: "3.1.0"
 info:
   title: "GreetingService"
   version: "1.0.0"

Package.swift

@@ -64,7 +64,7 @@ let package = Package(
         // Read OpenAPI documents
         .package(
             url: "https://github.com/mattpolzin/OpenAPIKit.git",
-            exact: "3.0.0-beta.1"
+            exact: "3.0.0-beta.2"
         ),
         .package(
             url: "https://github.com/jpsim/Yams.git",
@@ -91,7 +91,9 @@ let package = Package(
         .target(
             name: "_OpenAPIGeneratorCore",
             dependencies: [
+                .product(name: "OpenAPIKit", package: "OpenAPIKit"),
                 .product(name: "OpenAPIKit30", package: "OpenAPIKit"),
+                .product(name: "OpenAPIKitCompat", package: "OpenAPIKit"),
                 .product(name: "Algorithms", package: "swift-algorithms"),
                 .product(name: "Yams", package: "Yams"),
                 .product(name: "SwiftSyntax", package: "swift-syntax"),

README.md

@@ -29,8 +29,10 @@ Choose one of the transports listed below, or create your own by adopting the `C
 
 ## Requirements and supported features
 
-- Swift 5.8
-- OpenAPI 3.0.x
+| Generator versions | Supported OpenAPI versions | Minimum Swift version |
+| -------- | ------- | ----- |
+| `0.1.0` ... `0.1.11` | 3.0 | 5.8 |
+| `0.1.12` ... `main` | 3.0, 3.1 | 5.8 |
 
 ### Supported platforms and minimum versions
 

Sources/_OpenAPIGeneratorCore/Diagnostics.swift

@@ -12,7 +12,7 @@
 //
 //===----------------------------------------------------------------------===//
 import Foundation
-import OpenAPIKit30
+import OpenAPIKit
 
 /// A message emitted by the generator.
 public struct Diagnostic: Error, Codable {

Sources/_OpenAPIGeneratorCore/Extensions/OpenAPIKit.swift

@@ -11,7 +11,7 @@
 // SPDX-License-Identifier: Apache-2.0
 //
 //===----------------------------------------------------------------------===//
-import OpenAPIKit30
+import OpenAPIKit
 
 extension Either {
 
@@ -20,7 +20,7 @@ extension Either {
     /// - Parameter components: The Components section of the OpenAPI document.
     func resolve(
         in components: OpenAPI.Components
-    ) throws -> B where A == JSONReference<B> {
+    ) throws -> B where A == OpenAPI.Reference<B> {
         switch self {
         case let .a(a):
             return try components.lookup(a)
@@ -59,6 +59,8 @@ extension JSONSchema.Schema {
             return "reference"
         case .fragment:
             return "fragment"
+        case .null:
+            return "null"
         }
     }
 
@@ -89,6 +91,8 @@ extension JSONSchema.Schema {
             return nil
         case .fragment(let coreContext):
             return coreContext.formatString
+        case .null:
+            return nil
         }
     }
 

Sources/_OpenAPIGeneratorCore/GeneratorPipeline.swift

@@ -11,7 +11,7 @@
 // SPDX-License-Identifier: Apache-2.0
 //
 //===----------------------------------------------------------------------===//
-import OpenAPIKit30
+import OpenAPIKit
 import Foundation
 import Yams
 

Sources/_OpenAPIGeneratorCore/Layers/ParsedOpenAPIRepresentation.swift

@@ -11,7 +11,7 @@
 // SPDX-License-Identifier: Apache-2.0
 //
 //===----------------------------------------------------------------------===//
-import OpenAPIKit30
+import OpenAPIKit
 
 /// An OpenAPIKit document that contains the operations and types for which the generator emits Swift types.
 typealias ParsedOpenAPIRepresentation = OpenAPI.Document

Sources/_OpenAPIGeneratorCore/Parser/YamsParser.swift

@@ -12,7 +12,9 @@
 //
 //===----------------------------------------------------------------------===//
 import Foundation
+import OpenAPIKit
 import OpenAPIKit30
+import OpenAPIKitCompat
 import Yams
 
 /// A parser that uses the Yams library to parse the provided
@@ -44,21 +46,27 @@ struct YamsParser: ParserProtocol {
         guard let openAPIVersion = versionedDocument.openapi else {
             throw Diagnostic.openAPIMissingVersionError(location: .init(filePath: input.absolutePath.path))
         }
-        switch openAPIVersion {
-        case "3.0.0", "3.0.1", "3.0.2", "3.0.3":
-            break
-        default:
-            throw Diagnostic.openAPIVersionError(
-                versionString: "openapi: \(openAPIVersion)",
-                location: .init(filePath: input.absolutePath.path)
-            )
-        }
-
         do {
-            return try decoder.decode(
-                OpenAPI.Document.self,
-                from: input.contents
-            )
+            let document: OpenAPIKit.OpenAPI.Document
+            switch openAPIVersion {
+            case "3.0.0", "3.0.1", "3.0.2", "3.0.3":
+                let openAPI30Document = try decoder.decode(
+                    OpenAPIKit30.OpenAPI.Document.self,
+                    from: input.contents
+                )
+                document = openAPI30Document.convert(to: .v3_1_0)
+            case "3.1.0":
+                document = try decoder.decode(
+                    OpenAPIKit.OpenAPI.Document.self,
+                    from: input.contents
+                )
+            default:
+                throw Diagnostic.openAPIVersionError(
+                    versionString: "openapi: \(openAPIVersion)",
+                    location: .init(filePath: input.absolutePath.path)
+                )
+            }
+            return document
         } catch DecodingError.dataCorrupted(let errorContext) {
             try checkParsingError(context: errorContext, input: input)
             throw DecodingError.dataCorrupted(errorContext)
@@ -104,7 +112,7 @@ extension Diagnostic {
     static func openAPIVersionError(versionString: String, location: Location) -> Diagnostic {
         return error(
             message:
-                "Unsupported document version: \(versionString). Please provide a document with OpenAPI versions in the 3.0.x set.",
+                "Unsupported document version: \(versionString). Please provide a document with OpenAPI versions in the 3.0.x or 3.1.x sets.",
             location: location
         )
     }
@@ -115,7 +123,7 @@ extension Diagnostic {
     static func openAPIMissingVersionError(location: Location) -> Diagnostic {
         return error(
             message:
-                "No openapi key found, please provide a valid OpenAPI document with OpenAPI versions in the 3.0.x set.",
+                "No openapi key found, please provide a valid OpenAPI document with OpenAPI versions in the 3.0.x or 3.1.x sets.",
             location: location
         )
     }

Sources/_OpenAPIGeneratorCore/Translator/ClientTranslator/ClientTranslator.swift

@@ -11,7 +11,7 @@
 // SPDX-License-Identifier: Apache-2.0
 //
 //===----------------------------------------------------------------------===//
-import OpenAPIKit30
+import OpenAPIKit
 
 /// A translator for the generated client.
 ///

Sources/_OpenAPIGeneratorCore/Translator/ClientTranslator/translateClientMethod.swift

@@ -11,7 +11,7 @@
 // SPDX-License-Identifier: Apache-2.0
 //
 //===----------------------------------------------------------------------===//
-import OpenAPIKit30
+import OpenAPIKit
 
 extension ClientFileTranslator {