change implementation to not support decoding unknown new OAS versions

Author: mattpolzin

Sources/OpenAPIKit/Document/Document.swift

@@ -424,6 +424,12 @@ extension OpenAPI.Document {
     /// OpenAPIKit only explicitly supports versions that can be found in
     /// this enum. Other versions may or may not be decodable by
     /// OpenAPIKit to a certain extent.
+    ///
+    ///**IMPORTANT**: Although the `v3_1_x` case supports arbitrary
+    /// patch versions, only _known_ patch versions are decodable. That is, if the OpenAPI
+    /// specification releases a new patch version, OpenAPIKit will see a patch version release
+    /// explicitly supports decoding documents of that new patch version before said version will
+    /// succesfully decode as the `v3_1_x` case.
     public enum Version: RawRepresentable, Equatable, Codable {
         case v3_1_0
         case v3_1_1
@@ -444,6 +450,12 @@ extension OpenAPI.Document {
               guard let patchVersion = Int(components[2], radix: 10) else {
                   return nil
               }
+              // to support newer versions released in the future without a breaking
+              // change to the enumeration, bump the upper limit here to e.g. 2 or 3
+              // or 6:
+              guard patchVersion > 1 && patchVersion <= 1 else {
+                  return nil
+              }
               self = .v3_1_x(x: patchVersion)
           }
       }

Sources/OpenAPIKit30/Document/Document.swift

@@ -408,7 +408,13 @@ extension OpenAPI.Document {
     /// OpenAPIKit only explicitly supports versions that can be found in
     /// this enum. Other versions may or may not be decodable by
     /// OpenAPIKit to a certain extent.
-    public enum Version: RawRepresentable, Equatable, Codable {
+    ///
+    ///**IMPORTANT**: Although the `v3_0_x` case supports arbitrary
+    /// patch versions, only _known_ patch versions are decodable. That is, if the OpenAPI
+    /// specification releases a new patch version, OpenAPIKit will see a patch version release
+    /// explicitly supports decoding documents of that new patch version before said version will
+    /// succesfully decode as the `v3_0_x` case.
+  public enum Version: RawRepresentable, Equatable, Codable {
         case v3_0_0
         case v3_0_1
         case v3_0_2
@@ -434,6 +440,12 @@ extension OpenAPI.Document {
                 guard let patchVersion = Int(components[2], radix: 10) else {
                     return nil
                 }
+                // to support newer versions released in the future without a breaking
+                // change to the enumeration, bump the upper limit here to e.g. 5 or 6
+                // or 9:
+                guard patchVersion > 4 && patchVersion <= 4 else {
+                  return nil
+                }
                 self = .v3_0_x(x: patchVersion)
             }
         }

Tests/OpenAPIKit30Tests/Document/DocumentTests.swift

@@ -75,8 +75,9 @@ final class DocumentTests: XCTestCase {
         let t11 = OpenAPI.Document.Version(rawValue: "3.0.4")
         XCTAssertEqual(t11, .v3_0_4)
 
+        // not a known version:
         let t12 = OpenAPI.Document.Version(rawValue: "3.0.8")
-        XCTAssertEqual(t12, .v3_0_x(x: 8))
+        XCTAssertNil(t12)
     }
 
     func test_getRoutes() {

Tests/OpenAPIKitTests/Document/DocumentTests.swift

@@ -57,8 +57,9 @@ final class DocumentTests: XCTestCase {
         let t5 = OpenAPI.Document.Version(rawValue: "3.1.1")
         XCTAssertEqual(t5, .v3_1_1)
 
+        // not a known version:
         let t6 = OpenAPI.Document.Version(rawValue: "3.1.8")
-        XCTAssertEqual(t6, .v3_1_x(x: 8))
+        XCTAssertNil(t6)
     }
 
     func test_getRoutes() {