Add additionalOperations to PathItem type. Expand HttpMethod type to support additional methods not built into library.

Author: mattpolzin

Sources/OpenAPIKit/Path Item/DereferencedPathItem.swift

@@ -37,6 +37,11 @@ public struct DereferencedPathItem: Equatable {
     /// The dereferenced QUERY operation, if defined.
     public let query: DereferencedOperation?
 
+    /// Additional operations, keyed by all-caps HTTP method names. This
+    /// map MUST NOT contain any entries that can be represented by the
+    /// fixed fields on this type (e.g. `post`, `get`, etc.).
+    public var additionalOperations: OrderedDictionary<OpenAPI.HttpMethod, DereferencedOperation>
+
     public subscript<T>(dynamicMember path: KeyPath<OpenAPI.PathItem, T>) -> T {
         return underlyingPathItem[keyPath: path]
     }
@@ -68,6 +73,8 @@ public struct DereferencedPathItem: Equatable {
         self.trace = try pathItem.trace.map { try DereferencedOperation($0, resolvingIn: components, following: references) }
         self.query = try pathItem.query.map { try DereferencedOperation($0, resolvingIn: components, following: references) }
 
+        self.additionalOperations = try pathItem.additionalOperations.mapValues { try DereferencedOperation($0, resolvingIn: components, following: references) }
+
         var pathItem = pathItem
         if let name {
             pathItem.vendorExtensions[OpenAPI.Components.componentNameExtension] = .init(name)
@@ -83,24 +90,20 @@ extension DereferencedPathItem {
     /// Retrieve the operation for the given verb, if one is set for this path.
     public func `for`(_ verb: OpenAPI.HttpMethod) -> DereferencedOperation? {
         switch verb {
-        case .delete:
-            return self.delete
-        case .get:
-            return self.get
-        case .head:
-            return self.head
-        case .options:
-            return self.options
-        case .patch:
-            return self.patch
-        case .post:
-            return self.post
-        case .put:
-            return self.put
-        case .trace:
-            return self.trace
-        case .query:
-            return self.query
+        case .builtin(let builtin):
+            switch builtin {
+            case .delete: self.delete
+            case .get: self.get
+            case .head: self.head
+            case .options: self.options
+            case .patch: self.patch
+            case .post: self.post
+            case .put: self.put
+            case .trace: self.trace
+            case .query: self.query
+            }
+        case .other(let other):
+            additionalOperations[.other(other)]
         }
     }
 
@@ -122,9 +125,11 @@ extension DereferencedPathItem {
     /// - Returns: An array of `Endpoints` with the method (i.e. `.get`) and the operation for
     ///     the method.
     public var endpoints: [Endpoint] {
-        return OpenAPI.HttpMethod.allCases.compactMap { method in
-            self.for(method).map { .init(method: method, operation: $0) }
+        let builtins = OpenAPI.BuiltinHttpMethod.allCases.compactMap { method -> Endpoint? in
+            self.for(.builtin(method)).map { .init(method: .builtin(method), operation: $0) }
         }
+
+        return builtins + additionalOperations.map { key, value in .init(method: key, operation: value) }
     }
 }
 
@@ -158,6 +163,8 @@ extension OpenAPI.PathItem: ExternallyDereferenceable {
         let oldTrace = trace
         let oldQuery = query
 
+        let oldAdditionalOperations = additionalOperations
+
         async let (newParameters, c1, m1) = oldParameters.externallyDereferenced(with: loader)
 //        async let (newServers, c2, m2) = oldServers.externallyDereferenced(with: loader)
         async let (newGet, c3, m3) = oldGet.externallyDereferenced(with: loader)
@@ -170,6 +177,8 @@ extension OpenAPI.PathItem: ExternallyDereferenceable {
         async let (newTrace, c10, m10) = oldTrace.externallyDereferenced(with: loader)
         async let (newQuery, c11, m11) = oldQuery.externallyDereferenced(with: loader)
 
+        async let (newAdditionalOperations, c12, m12) = oldAdditionalOperations.externallyDereferenced(with: loader)
+
         var pathItem = self
         var newComponents = try await c1
         var newMessages = try await m1
@@ -187,6 +196,7 @@ extension OpenAPI.PathItem: ExternallyDereferenceable {
         pathItem.patch = try await newPatch
         pathItem.trace = try await newTrace
         pathItem.query = try await newQuery
+        pathItem.additionalOperations = try await newAdditionalOperations
 
         try await newComponents.merge(c3)
         try await newComponents.merge(c4)
@@ -197,6 +207,7 @@ extension OpenAPI.PathItem: ExternallyDereferenceable {
         try await newComponents.merge(c9)
         try await newComponents.merge(c10)
         try await newComponents.merge(c11)
+        try await newComponents.merge(c12)
 
         try await newMessages += m3
         try await newMessages += m4
@@ -207,6 +218,7 @@ extension OpenAPI.PathItem: ExternallyDereferenceable {
         try await newMessages += m9
         try await newMessages += m10
         try await newMessages += m11
+        try await newMessages += m12
 
         if let oldServers {
             async let (newServers, c2, m2) = oldServers.externallyDereferenced(with: loader)

Sources/OpenAPIKit/Path Item/PathItem.swift

@@ -57,6 +57,11 @@ extension OpenAPI {
         /// The `QUERY` endpoint at this path, if one exists.
         public var query: Operation?
 
+        /// Additional operations, keyed by all-caps HTTP method names. This
+        /// map MUST NOT contain any entries that can be represented by the
+        /// fixed fields on this type (e.g. `post`, `get`, etc.).
+        public var additionalOperations: OrderedDictionary<OpenAPI.HttpMethod, Operation>
+
         /// Dictionary of vendor extensions.
         ///
         /// These should be of the form:
@@ -84,6 +89,7 @@ extension OpenAPI {
             patch: Operation? = nil,
             trace: Operation? = nil,
             query: Operation? = nil,
+            additionalOperations: OrderedDictionary<OpenAPI.HttpMethod, Operation> = [:],
             vendorExtensions: [String: AnyCodable] = [:]
         ) {
             self.summary = summary
@@ -100,11 +106,14 @@ extension OpenAPI {
             self.patch = patch
             self.trace = trace
             self.query = query
+            self.additionalOperations = additionalOperations
             self.vendorExtensions = vendorExtensions
 
             self.conditionalWarnings = [
                 // If query is non-nil, the document must be OAS version 3.2.0 or greater
-                nonNilVersionWarning(fieldName: "query", value: query, minimumVersion: .v3_2_0)
+                nonNilVersionWarning(fieldName: "query", value: query, minimumVersion: .v3_2_0),
+                // If there are additionalOperations defiend, the document must be OAS version 3.2.0 or greater
+                nonEmptyVersionWarning(fieldName: "additionalOperations", value: additionalOperations, minimumVersion: .v3_2_0)
             ].compactMap { $0 }
         }
 
@@ -170,6 +179,7 @@ extension OpenAPI.PathItem: Equatable {
         && lhs.patch == rhs.patch
         && lhs.trace == rhs.trace
         && lhs.query == rhs.query
+        && lhs.additionalOperations == rhs.additionalOperations
         && lhs.vendorExtensions == rhs.vendorExtensions
     }
 }
@@ -183,6 +193,15 @@ fileprivate func nonNilVersionWarning<Subject>(fieldName: String, value: Subject
     }
 }
 
+fileprivate func nonEmptyVersionWarning<Key,  Value>(fieldName: String, value: OrderedDictionary<Key, Value>, minimumVersion: OpenAPI.Document.Version) -> (any Condition, OpenAPI.Warning)? {
+    if value.isEmpty { return nil }
+
+    return OpenAPI.Document.ConditionalWarnings.version(
+        lessThan: minimumVersion,
+        doesNotSupport: "The PathItem \(fieldName) map"
+    )
+}
+
 extension OpenAPI.PathItem {
     public typealias Map = OrderedDictionary<OpenAPI.Path, Either<OpenAPI.Reference<OpenAPI.PathItem>, OpenAPI.PathItem>>
 }
@@ -198,48 +217,49 @@ extension OpenAPI.PathItem {
     /// Retrieve the operation for the given verb, if one is set for this path.
     public func `for`(_ verb: OpenAPI.HttpMethod) -> OpenAPI.Operation? {
         switch verb {
-        case .delete:
-            return self.delete
-        case .get:
-            return self.get
-        case .head:
-            return self.head
-        case .options:
-            return self.options
-        case .patch:
-            return self.patch
-        case .post:
-            return self.post
-        case .put:
-            return self.put
-        case .trace:
-            return self.trace
-        case .query:
-            return self.query
+        case .builtin(let builtin):
+            switch builtin {
+            case .delete: self.delete
+            case .get: self.get
+            case .head: self.head
+            case .options: self.options
+            case .patch: self.patch
+            case .post: self.post
+            case .put: self.put
+            case .trace: self.trace
+            case .query: self.query
+            }
+        case .other(let other):
+            additionalOperations[.other(other)]
         }
     }
 
     /// Set the operation for the given verb, overwriting any already set operation for the same verb.
     public mutating func set(operation: OpenAPI.Operation?, for verb: OpenAPI.HttpMethod) {
         switch verb {
-        case .delete:
-            self.delete(operation)
-        case .get:
-            self.get(operation)
-        case .head:
-            self.head(operation)
-        case .options:
-            self.options(operation)
-        case .patch:
-            self.patch(operation)
-        case .post:
-            self.post(operation)
-        case .put:
-            self.put(operation)
-        case .trace:
-            self.trace(operation)
-        case .query:
-            self.query(operation)
+        case .builtin(let builtin):
+            switch builtin {
+            case .delete:
+                self.delete(operation)
+            case .get:
+                self.get(operation)
+            case .head:
+                self.head(operation)
+            case .options:
+                self.options(operation)
+            case .patch:
+                self.patch(operation)
+            case .post:
+                self.post(operation)
+            case .put:
+                self.put(operation)
+            case .trace:
+                self.trace(operation)
+            case .query:
+                self.query(operation)
+            }
+        case .other(let other):
+            self.additionalOperations[.other(other)] = operation
         }
     }
 
@@ -264,9 +284,11 @@ extension OpenAPI.PathItem {
     /// - Returns: An array of `Endpoints` with the method (i.e. `.get`) and the operation for
     ///     the method.
     public var endpoints: [Endpoint] {
-        return OpenAPI.HttpMethod.allCases.compactMap { method in
-            self.for(method).map { .init(method: method, operation: $0) }
+        let builtins = OpenAPI.BuiltinHttpMethod.allCases.compactMap { method -> Endpoint? in
+            self.for(.builtin(method)).map { .init(method: .builtin(method), operation: $0) }
         }
+
+        return builtins + additionalOperations.map { key, value in .init(method: key, operation: value) }
     }
 }
 
@@ -312,6 +334,10 @@ extension OpenAPI.PathItem: Encodable {
         try container.encodeIfPresent(trace, forKey: .trace)
         try container.encodeIfPresent(query, forKey: .query)
 
+        if !additionalOperations.isEmpty {
+            try container.encode(additionalOperations, forKey: .additionalOperations)
+        }
+
         if VendorExtensionsConfiguration.isEnabled(for: encoder) {
             try encodeExtensions(to: &container)
         }
@@ -338,11 +364,15 @@ extension OpenAPI.PathItem: Decodable {
             trace = try container.decodeIfPresent(OpenAPI.Operation.self, forKey: .trace)
             query = try container.decodeIfPresent(OpenAPI.Operation.self, forKey: .query)
 
+            additionalOperations = try container.decodeIfPresent(OrderedDictionary<OpenAPI.HttpMethod, OpenAPI.Operation>.self, forKey: .additionalOperations) ?? [:]
+
             vendorExtensions = try Self.extensions(from: decoder)
 
             self.conditionalWarnings = [
                 // If query is non-nil, the document must be OAS version 3.2.0 or greater
-                nonNilVersionWarning(fieldName: "query", value: query, minimumVersion: .v3_2_0)
+                nonNilVersionWarning(fieldName: "query", value: query, minimumVersion: .v3_2_0),
+                // If there are additionalOperations defiend, the document must be OAS version 3.2.0 or greater
+                nonEmptyVersionWarning(fieldName: "additionalOperations", value: additionalOperations, minimumVersion: .v3_2_0)
             ].compactMap { $0 }
         } catch let error as DecodingError {
 
@@ -377,6 +407,8 @@ extension OpenAPI.PathItem {
         case trace
         case query
 
+        case additionalOperations
+
         case extended(String)
 
         static var allBuiltinKeys: [CodingKeys] {
@@ -394,7 +426,9 @@ extension OpenAPI.PathItem {
                 .head,
                 .patch,
                 .trace,
-                .query
+                .query,
+
+                .additionalOperations
             ]
         }
 
@@ -430,6 +464,8 @@ extension OpenAPI.PathItem {
                 self = .trace
             case "query":
                 self = .query
+            case "additionalOperations":
+                self = .additionalOperations
             default:
                 self = .extendedKey(for: stringValue)
             }
@@ -463,6 +499,8 @@ extension OpenAPI.PathItem {
                 return "trace"
             case .query:
                 return "query"
+            case .additionalOperations:
+                return "additionalOperations"
             case .extended(let key):
                 return key
             }