WIP branch tracking the v6.0.0 release

.github/workflows/codecov.yml

@@ -5,7 +5,7 @@ on: [pull_request]
 jobs:
   codecov:
     container: 
-      image: swift:5.10
+      image: swift:6.2
     runs-on: ubuntu-latest
     steps:
     - uses: actions/checkout@v5

.github/workflows/documentation.yml

@@ -9,7 +9,7 @@ jobs:
   build:
     runs-on: ubuntu-latest
     container: 
-      image: swift:5.10
+      image: swift:6.2
 
     steps:
       - uses: actions/checkout@v5

.github/workflows/tests.yml

@@ -13,18 +13,15 @@ jobs:
       fail-fast: false
       matrix:
         image:
-          - swift:5.10-focal
-          - swift:5.10-jammy
-          - swift:6.0-focal
-          - swift:6.0-jammy
-          - swift:6.0-noble
           - swift:6.1-focal
           - swift:6.1-jammy
           - swift:6.1-noble
           - swift:6.2-jammy
           - swift:6.2-noble
+          - swift:6.3-jammy
+          - swift:6.3-noble
           - swiftlang/swift:nightly-focal
-#          - swiftlang/swift:nightly-jammy
+          - swiftlang/swift:nightly-jammy
     container: ${{ matrix.image }}
     steps:
     - name: Checkout code
@@ -36,7 +33,6 @@ jobs:
       fail-fast: false
       matrix:
         os:
-          - macos-14
           - macos-15
     runs-on: ${{ matrix.os }}
     steps:

.github/workflows/traits.yml

@@ -0,0 +1,12 @@
+name: Traits
+
+on: [pull_request]
+
+jobs:
+  without-default-traits:
+    container: 
+      image: swift:6.3
+    runs-on: ubuntu-latest
+    steps:
+    - uses: actions/checkout@v5
+    - run: swift test --enable-test-discovery --disable-default-traits

Package.swift

@@ -1,4 +1,4 @@
-// swift-tools-version: 5.10
+// swift-tools-version: 6.1
 
 import PackageDescription
 
@@ -19,9 +19,16 @@ let package = Package(
             name: "OpenAPIKitCompat",
             targets: ["OpenAPIKitCompat"]),
     ],
+    traits: [
+        .init(
+            name: "ExternalLoading",
+            description: "A framework that allows using OpenAPIKit for loading external JSON references into the Components Object. Building OpenAPKit with this capability is notably slower given its use of Swift Concurrency."
+        ),
+        .default(enabledTraits: ["ExternalLoading"])
+    ],
     dependencies: [
         .package(url: "https://github.com/apple/swift-docc-plugin", from: "1.0.0"),
-        .package(url: "https://github.com/jpsim/Yams.git", "5.1.0"..<"7.0.0") // just for tests
+        .package(url: "https://github.com/jpsim/Yams.git", "6.0.0"..<"7.0.0") // just for tests
     ],
     targets: [
         .target(
@@ -74,5 +81,5 @@ let package = Package(
             name: "OpenAPIKitCompatTests",
             dependencies: ["OpenAPIKitCompat"])
     ],
-    swiftLanguageVersions: [ .v5 ]
+    swiftLanguageModes: [ .v5, .v6 ]
 )

README.md

@@ -1,4 +1,4 @@
-[![sswg:sandbox|94x20](https://img.shields.io/badge/sswg-sandbox-lightgrey.svg)](https://github.com/swift-server/sswg/blob/master/process/incubation.md#sandbox-level) [![Swift 5.10+](http://img.shields.io/badge/Swift-5.10+-blue.svg)](https://swift.org)
+[![sswg:sandbox|94x20](https://img.shields.io/badge/sswg-sandbox-lightgrey.svg)](https://github.com/swift-server/sswg/blob/master/process/incubation.md#sandbox-level) [![Swift 6.1+](http://img.shields.io/badge/Swift-6.1+-blue.svg)](https://swift.org)
 
 [![MIT license](http://img.shields.io/badge/license-MIT-lightgrey.svg)](http://opensource.org/licenses/MIT) ![Tests](https://github.com/mattpolzin/OpenAPIKit/actions/workflows/tests.yml/badge.svg?branch=main)
 
@@ -16,9 +16,9 @@ versions and key features are supported by which OpenAPIKit versions.
 
 | OpenAPIKit | Swift | OpenAPI v3.0, v3.1 | External Dereferencing & Sendable | OpenAPI v3.2 |
 |------------|-------|--------------------|-----------------------------------|--------------|
-| v3.x       | 5.1+  | ✅                 |                                   |              |
 | v4.x       | 5.8+  | ✅                 | ✅                                |              |
 | v5.x       | 5.10+ | ✅                 | ✅                                | ✅           |
+| v6.x       | 6.1+  | ✅                 | ✅                                | ✅           |
 
 - [Usage](#usage)
   - [Migration](#migration)
@@ -215,6 +215,25 @@ You could also call `oldDoc?.convert(to: .v3_1_4)` if you specifically wanted to
 work against a 3.1.x document for whatever reason (possibly because you wanted
 to reserialize the document at a 3.1.x version).
 
+### Traits
+The OpenAPIKit package offers an `"ExternalLoading"` trait that is enabled by
+default. External Loading (i.e. loading multiple OpenAPI files in order to
+resolve references between them) uses Swift Concurrency to parallelize loading
+of each file. Swift Concurrency adds enough overhead to the compilation time of
+OpenAPIKit that it might be worth disabling this trait if you do not need the
+External Loading capability. Note that it is _compile time_ that takes a hit
+from enabling External Loading, not _runtime speed_.
+
+To disable External Loading features, depend on OpenAPIKit with an empty
+`traits` argument:
+```swift
+.package(
+  url: "https://github/com/mattpolzin/openapikit.git",
+  from: "6.0.0",
+  traits: []
+)
+```
+
 ### A note on dictionary ordering
 The **Foundation** library's `JSONEncoder` and `JSONDecoder` do not make any
 guarantees about the ordering of keyed containers. This means decoding a JSON

Sources/OpenAPIKit/Components Object/Components.swift

@@ -439,6 +439,7 @@ extension OpenAPI.Components {
 }
 
 extension OpenAPI.Components {
+#if ExternalLoading
     internal mutating func externallyDereference<Loader: ExternalLoader>(with loader: Loader.Type, depth: ExternalDereferenceDepth = .iterations(1), context: [Loader.Message] = []) async throws -> [Loader.Message] {
         if case let .iterations(number) = depth,
            number <= 0 {
@@ -542,6 +543,7 @@ extension OpenAPI.Components {
                 return try await externallyDereference(with: loader, depth: .full, context: newMessages)
         }
     }
+#endif
 }
 
 extension OpenAPI.Components: Validatable {}

Sources/OpenAPIKit/Content/DereferencedContent.swift

@@ -96,6 +96,7 @@ extension OpenAPI.Content: LocallyDereferenceable {
 }
 
 extension OpenAPI.Content: ExternallyDereferenceable {
+#if ExternalLoading
     public func externallyDereferenced<Loader: ExternalLoader>(with loader: Loader.Type) async throws -> (Self, OpenAPI.Components, [Loader.Message]) { 
       let oldSchema = schema
       let oldItemSchema = itemSchema
@@ -140,4 +141,5 @@ extension OpenAPI.Content: ExternallyDereferenceable {
 
         return (newContent, newComponents, newMessages)
     }
+#endif
 }

Sources/OpenAPIKit/Content/DereferencedContentEncoding.swift

@@ -58,6 +58,7 @@ extension OpenAPI.Content.Encoding: LocallyDereferenceable {
 }
 
 extension OpenAPI.Content.Encoding: ExternallyDereferenceable {
+#if ExternalLoading
     public func externallyDereferenced<Loader: ExternalLoader>(with loader: Loader.Type) async throws -> (Self, OpenAPI.Components, [Loader.Message]) { 
         let newHeaders: OpenAPI.Header.Map?
         let newComponents: OpenAPI.Components
@@ -81,4 +82,5 @@ extension OpenAPI.Content.Encoding: ExternallyDereferenceable {
 
         return (newEncoding, newComponents, newMessages)
     }
+#endif
 }

Sources/OpenAPIKit/Document/Document.swift

@@ -398,6 +398,7 @@ extension OpenAPI.Document {
         return try DereferencedDocument(self)
     }
 
+#if ExternalLoading
     /// Load all remote references into the document. A remote reference is one
     /// that points to another file rather than a location within the
     /// same file.
@@ -437,6 +438,7 @@ extension OpenAPI.Document {
 
         return try await context + m1 + m2 + m3
     }
+#endif
 }
 
 extension OpenAPI {

Sources/OpenAPIKit/Either/Either+ExternallyDereferenceable.swift

@@ -10,6 +10,7 @@ import OpenAPIKitCore
 // MARK: - ExternallyDereferenceable
 extension Either: ExternallyDereferenceable where A: ExternallyDereferenceable, B: ExternallyDereferenceable {
 
+#if ExternalLoading
     public func externallyDereferenced<Loader: ExternalLoader>(with loader: Loader.Type) async throws -> (Self, OpenAPI.Components, [Loader.Message]) { 
         switch self {
         case .a(let a):
@@ -20,4 +21,5 @@ extension Either: ExternallyDereferenceable where A: ExternallyDereferenceable,
            return (.b(newB), components, messages)
         }
     }
+#endif
 }

Sources/OpenAPIKit/Example/Example.swift

@@ -394,9 +394,11 @@ extension OpenAPI.Example: LocallyDereferenceable {
 }
 
 extension OpenAPI.Example: ExternallyDereferenceable {
+#if ExternalLoading
     public func externallyDereferenced<Loader: ExternalLoader>(with loader: Loader.Type) async throws -> (Self, OpenAPI.Components, [Loader.Message]) { 
         return (self, .init(), [])
     }
+#endif
 }
 
 extension OpenAPI.Example: Validatable {}

Sources/OpenAPIKit/ExternalLoader.swift

@@ -49,5 +49,7 @@ public protocol ExternalLoader: _ExternalLoaderMetatype where Message: Sendable
 }
 
 public protocol ExternallyDereferenceable {
+#if ExternalLoading
     func externallyDereferenced<Loader: ExternalLoader>(with loader: Loader.Type) async throws -> (Self, OpenAPI.Components, [Loader.Message])
+#endif
 }

Sources/OpenAPIKit/Header/DereferencedHeader.swift

@@ -84,6 +84,7 @@ extension OpenAPI.Header: LocallyDereferenceable {
 }
 
 extension OpenAPI.Header: ExternallyDereferenceable {
+#if ExternalLoading
     public func externallyDereferenced<Loader: ExternalLoader>(with loader: Loader.Type) async throws -> (Self, OpenAPI.Components, [Loader.Message]) { 
 
         // if not for a Swift bug, this whole next bit would just be the
@@ -117,4 +118,5 @@ extension OpenAPI.Header: ExternallyDereferenceable {
 
         return (newHeader, newComponents, newMessages)
     }
+#endif
 }

Sources/OpenAPIKit/JSONReference.swift

@@ -602,6 +602,7 @@ extension JSONReference: LocallyDereferenceable where ReferenceType: LocallyDere
 }
 
 extension JSONReference: ExternallyDereferenceable where ReferenceType: ExternallyDereferenceable & Decodable & Equatable {
+#if ExternalLoading
     public func externallyDereferenced<Loader: ExternalLoader>(with loader: Loader.Type) async throws -> (Self, OpenAPI.Components, [Loader.Message]) { 
         switch self {
         case .internal(let ref):
@@ -619,6 +620,7 @@ extension JSONReference: ExternallyDereferenceable where ReferenceType: External
             return (try components.reference(named: componentKey.rawValue, ofType: ReferenceType.self).jsonReference, components, messages)
         }
     }
+#endif
 }
 
 extension OpenAPI.Reference: LocallyDereferenceable where ReferenceType: LocallyDereferenceable {
@@ -649,10 +651,12 @@ extension OpenAPI.Reference: LocallyDereferenceable where ReferenceType: Locally
 }
 
 extension OpenAPI.Reference: ExternallyDereferenceable where ReferenceType: ExternallyDereferenceable & Decodable & Equatable {
+#if ExternalLoading
     public func externallyDereferenced<Loader: ExternalLoader>(with loader: Loader.Type) async throws -> (Self, OpenAPI.Components, [Loader.Message]) { 
         let (newRef, components, messages) = try await jsonReference.externallyDereferenced(with: loader)
         return (.init(newRef), components, messages)
     }
+#endif
 }
 
 extension OpenAPI.Reference: Validatable where ReferenceType: Validatable {}

Sources/OpenAPIKit/Link.swift

@@ -294,6 +294,7 @@ extension OpenAPI.Link: LocallyDereferenceable {
 }
 
 extension OpenAPI.Link: ExternallyDereferenceable {
+#if ExternalLoading
     public func externallyDereferenced<Loader: ExternalLoader>(with loader: Loader.Type) async throws -> (Self, OpenAPI.Components, [Loader.Message]) { 
         let (newServer, newComponents, newMessages) = try await server.externallyDereferenced(with: loader)
 
@@ -302,6 +303,7 @@ extension OpenAPI.Link: ExternallyDereferenceable {
 
         return (newLink, newComponents, newMessages)
     }
+#endif
 }
 
 extension OpenAPI.Link: Validatable {}

Sources/OpenAPIKit/Operation/DereferencedOperation.swift

@@ -126,6 +126,7 @@ extension OpenAPI.Operation: LocallyDereferenceable {
 }
 
 extension OpenAPI.Operation: ExternallyDereferenceable {
+#if ExternalLoading
     public func externallyDereferenced<Loader: ExternalLoader>(with loader: Loader.Type) async throws -> (Self, OpenAPI.Components, [Loader.Message]) { 
         let oldParameters = parameters
         let oldRequestBody = requestBody
@@ -162,4 +163,5 @@ extension OpenAPI.Operation: ExternallyDereferenceable {
 
         return (newOperation, newComponents, newMessages)
     }
+#endif
 }

Sources/OpenAPIKit/Parameter/DereferencedParameter.swift

@@ -84,6 +84,7 @@ extension OpenAPI.Parameter: LocallyDereferenceable {
 }
 
 extension OpenAPI.Parameter: ExternallyDereferenceable {
+#if ExternalLoading
     public func externallyDereferenced<Loader: ExternalLoader>(with loader: Loader.Type) async throws -> (Self, OpenAPI.Components, [Loader.Message]) { 
 
         // if not for a Swift bug, this whole function would just be the
@@ -131,8 +132,10 @@ extension OpenAPI.Parameter: ExternallyDereferenceable {
 
         return (newParameter, newComponents, newMessages)
     }
+#endif
 }
 
+#if ExternalLoading
 fileprivate func externallyDereference<Loader: ExternalLoader>(
     schemaOrContent: Either<OpenAPI.Parameter.SchemaContext, OpenAPI.Content.Map>,
     with loader: Loader.Type
@@ -146,3 +149,4 @@ fileprivate func externallyDereference<Loader: ExternalLoader>(
         return (.b(map), components, messages)
     }
 }
+#endif

Sources/OpenAPIKit/Parameter/DereferencedSchemaContext.swift

@@ -71,6 +71,7 @@ extension OpenAPI.Parameter.SchemaContext: LocallyDereferenceable {
 }
 
 extension OpenAPI.Parameter.SchemaContext: ExternallyDereferenceable {
+#if ExternalLoading
     public func externallyDereferenced<Loader: ExternalLoader>(with loader: Loader.Type) async throws -> (Self, OpenAPI.Components, [Loader.Message]) { 
         let oldSchema = schema
 
@@ -91,4 +92,5 @@ extension OpenAPI.Parameter.SchemaContext: ExternallyDereferenceable {
 
         return (newSchemaContext, newComponents, newMessages)
     }
+#endif
 }

Sources/OpenAPIKit/Path Item/DereferencedPathItem.swift

@@ -152,6 +152,7 @@ extension OpenAPI.PathItem: LocallyDereferenceable {
 }
 
 extension OpenAPI.PathItem: ExternallyDereferenceable {
+#if ExternalLoading
     public func externallyDereferenced<Loader: ExternalLoader>(with loader: Loader.Type) async throws -> (Self, OpenAPI.Components, [Loader.Message]) { 
         let oldParameters = parameters
         let oldServers = servers
@@ -231,4 +232,5 @@ extension OpenAPI.PathItem: ExternallyDereferenceable {
 
         return (pathItem, newComponents, newMessages)
     }
+#endif
 }

Sources/OpenAPIKit/Request/DereferencedRequest.swift

@@ -63,6 +63,7 @@ extension OpenAPI.Request: LocallyDereferenceable {
 }
 
 extension OpenAPI.Request: ExternallyDereferenceable {
+#if ExternalLoading
     public func externallyDereferenced<Loader: ExternalLoader>(with loader: Loader.Type) async throws -> (Self, OpenAPI.Components, [Loader.Message]) { 
         var newRequest = self
 
@@ -71,4 +72,5 @@ extension OpenAPI.Request: ExternallyDereferenceable {
         newRequest.content = newContent
         return (newRequest, components, messages)
     }
+#endif
 }