Merge pull request #284 from mattpolzin/bugfix/280/path-item-references

Bugfix/280/path item references

Author: mattpolzin

Sources/OpenAPIKit/Document/DereferencedDocument.swift

@@ -32,6 +32,8 @@ public struct DereferencedDocument: Equatable {
     /// in the array.
     public let security: [DereferencedSecurityRequirement]
 
+
+
     public subscript<T>(dynamicMember path: KeyPath<OpenAPI.Document, T>) -> T {
         return underlyingDocument[keyPath: path]
     }
@@ -49,11 +51,7 @@ public struct DereferencedDocument: Equatable {
     ///     component in the same file that cannot be found in the Components Object.
     internal init(_ document: OpenAPI.Document) throws {
         self.paths = try document.paths.mapValues {
-            try DereferencedPathItem(
-                $0,
-                resolvingIn: document.components,
-                following: []
-            )
+            try $0._dereferenced(in: document.components, following: [])
         }
         self.security = try document.security.map {
             try DereferencedSecurityRequirement(
@@ -67,7 +65,13 @@ public struct DereferencedDocument: Equatable {
     }
 }
 
+// MARK: - Dereferenced Helpers
 extension DereferencedDocument {
+    // We override the following helpers defined on `Document`
+    // because they utilize `PathItems` which might be references
+    // on a `Document` but are guaranteed to be derefenced at this
+    // point
+
     /// The pairing of a path and the path item that describes the
     /// route at that path.
     public struct Route: Equatable {
@@ -89,8 +93,110 @@ extension DereferencedDocument {
     public var routes: [Route] {
         return paths.map { (path, pathItem) in .init(path: path, pathItem: pathItem) }
     }
+
+    /// Retrieve an array of all locally defined Operation Ids defined by
+    /// this API. These Ids are guaranteed to be unique by
+    /// the OpenAPI Specification.
+    ///
+    /// The ordering is not necessarily significant, but it will
+    /// be the order in which each operation is occurred within
+    /// each path, traversed in the order the paths appear in
+    /// the document.
+    ///
+    /// See [Operation Object](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.1.0.md#operation-object) in the specifcation.
+    ///
+    public var allOperationIds: [String] {
+        return paths.values
+            .flatMap { $0.endpoints }
+            .compactMap { $0.operation.operationId }
+    }
+
+    /// All servers referenced anywhere in the whole document.
+    ///
+    /// This property contains all servers defined at any level the document
+    /// and therefore may or may not contain servers not found in the
+    /// root servers array.
+    ///
+    /// The `servers` property on `OpenAPI.Document`, by contrast, contains
+    /// servers that are applicable to all paths and operations that
+    /// do not define their own `serves` array to override the root array.
+    ///
+    /// - Important: For the purposes of returning one of each `Server`,
+    ///     two servers are considered identical if they have the same `url`
+    ///     and `variables`. Differing `description` properties for
+    ///     otherwise identical servers are considered to be two ways to
+    ///     describe the same server. `vendorExtensions` are also
+    ///     ignored when determining server uniqueness.
+    ///
+    ///     The first `Server` encountered will be used, so if the only
+    ///     difference between a server at the root document level and
+    ///     one in an `Operation`'s override of the servers array is the
+    ///     description, the description of the `Server` returned by this
+    ///     property will be that of the root document definition.
+    ///
+    public var allServers: [OpenAPI.Server] {
+            // We hash `Variable` without its
+            // `description` or `vendorExtensions`.
+        func hash(variable: OpenAPI.Server.Variable, into hasher: inout Hasher) {
+            hasher.combine(variable.enum)
+            hasher.combine(variable.default)
+        }
+
+            // We hash `Server` without its `description` or
+            // `vendorExtensions`.
+        func hash(server: OpenAPI.Server, into hasher: inout Hasher) {
+            hasher.combine(server.urlTemplate)
+            for (key, value) in server.variables {
+                hasher.combine(key)
+                hash(variable: value, into: &hasher)
+            }
+        }
+
+        func hash(for server: OpenAPI.Server) -> Int {
+            var hasher = Hasher()
+            hash(server: server, into: &hasher)
+            return hasher.finalize()
+        }
+
+        var collectedServers = underlyingDocument.servers
+        var seenHashes = Set(underlyingDocument.servers.map(hash(for:)))
+
+        func insertUniquely(server: OpenAPI.Server) {
+            let serverHash = hash(for: server)
+            if !seenHashes.contains(serverHash) {
+                seenHashes.insert(serverHash)
+                collectedServers.append(server)
+            }
+        }
+
+        for pathItem in paths.values {
+            let pathItemServers = pathItem.servers ?? []
+            pathItemServers.forEach(insertUniquely)
+
+            let endpointServers: [OpenAPI.Server] =
+                pathItem.endpoints
+                .flatMap { $0.operation.servers ?? [] }
+            endpointServers.forEach(insertUniquely)
+        }
+
+        return collectedServers
+    }
+
+    /// All Tags used anywhere in the document.
+    ///
+    /// The tags stored in the `OpenAPI.Document.tags`
+    /// property need not contain all tags used anywhere in
+    /// the document. This property is comprehensive.
+    public var allTags: Set<String> {
+        return Set(
+            (underlyingDocument.tags ?? []).map { $0.name }
+            + paths.values.flatMap { $0.endpoints }
+                .flatMap { $0.operation.tags ?? [] }
+        )
+    }
 }
 
+// MARK: - ResolvedDocument
 extension DereferencedDocument {
     /// Resolve the document's routes and endpoints.
     ///

Sources/OpenAPIKit/Document/Document.swift

@@ -8,7 +8,7 @@
 import OpenAPIKitCore
 
 extension OpenAPI {
-    /// The root of an OpenAPI 3.0 document.
+    /// The root of an OpenAPI 3.1 document.
     /// 
     /// See [OpenAPI Specification](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.1.0.md).
     ///
@@ -204,18 +204,26 @@ extension OpenAPI.Document {
         }
     }
 
-    /// Get all routes for this document.
+    /// Get all locally defined routes for this document. PathItems will be
+    /// looked up in the components, but any remote references or path items
+    /// missing from the components will be ignored.
     ///
     /// - Returns: An Array of `Routes` with the path
     ///     and the definition of the route.
+    ///
     public var routes: [Route] {
-        return paths.map { (path, pathItem) in .init(path: path, pathItem: pathItem) }
+        return paths.compactMap { (path, pathItemRef) in
+            components[pathItemRef].map { .init(path: path, pathItem: $0) }
+        }
     }
 
-    /// Retrieve an array of all Operation Ids defined by
+    /// Retrieve an array of all locally defined Operation Ids defined by
     /// this API. These Ids are guaranteed to be unique by
     /// the OpenAPI Specification.
     ///
+    /// PathItems will be looked up in the components, but any remote references
+    /// or path items missing from the components will be ignored.
+    ///
     /// The ordering is not necessarily significant, but it will
     /// be the order in which each operation is occurred within
     /// each path, traversed in the order the paths appear in
@@ -225,6 +233,7 @@ extension OpenAPI.Document {
     ///
     public var allOperationIds: [String] {
         return paths.values
+            .compactMap { components[$0] }
             .flatMap { $0.endpoints }
             .compactMap { $0.operation.operationId }
     }
@@ -288,11 +297,12 @@ extension OpenAPI.Document {
         }
 
         for pathItem in paths.values {
-            let pathItemServers = pathItem.servers ?? []
+            let pathItemServers = components[pathItem]?.servers ?? []
             pathItemServers.forEach(insertUniquely)
 
-            let endpointServers = pathItem.endpoints.flatMap { $0.operation.servers ?? [] }
-            endpointServers.forEach(insertUniquely)
+            if let endpointServers = (components[pathItem]?.endpoints.flatMap { $0.operation.servers ?? [] }) {
+                endpointServers.forEach(insertUniquely)
+            }
         }
 
         return collectedServers
@@ -303,10 +313,12 @@ extension OpenAPI.Document {
     /// The tags stored in the `OpenAPI.Document.tags`
     /// property need not contain all tags used anywhere in
     /// the document. This property is comprehensive.
+    ///
     public var allTags: Set<String> {
         return Set(
             (tags ?? []).map { $0.name }
-            + paths.values.flatMap { $0.endpoints }
+            + paths.values.compactMap { components[$0] }
+                .flatMap { $0.endpoints }
                 .flatMap { $0.operation.tags ?? [] }
         )
     }
@@ -434,6 +446,9 @@ extension OpenAPI.Document: Decodable {
             throw OpenAPI.Error.Decoding.Document(error)
         } catch let error as DecodingError {
 
+            throw OpenAPI.Error.Decoding.Document(error)
+        } catch let error as EitherDecodeNoTypesMatchedError {
+
             throw OpenAPI.Error.Decoding.Document(error)
         }
     }
@@ -580,7 +595,9 @@ internal func decodeSecurityRequirements<CodingKeys: CodingKey>(from container:
 
 internal func validateSecurityRequirements(in paths: OpenAPI.PathItem.Map, against components: OpenAPI.Components) throws {
     for (path, pathItem) in paths {
-        for endpoint in pathItem.endpoints {
+        guard let pathItemValue = components[pathItem] else { continue }
+
+        for endpoint in pathItemValue.endpoints {
             if let securityRequirements = endpoint.operation.security {
                 try validate(
                     securityRequirements: securityRequirements,

Sources/OpenAPIKit/Either/Either+Convenience.swift

@@ -71,6 +71,11 @@ extension Either where A == DereferencedSchemaContext {
     }
 }
 
+extension Either where B == OpenAPI.PathItem {
+    /// Retrieve the path item if that is what this property contains.
+    public var pathItemValue: B? { b }
+}
+
 extension Either where B == OpenAPI.Parameter {
     /// Retrieve the parameter if that is what this property contains.
     public var parameterValue: B? { b }
@@ -126,11 +131,6 @@ extension Either where B == OpenAPI.Header {
     public var headerValue: B? { b }
 }
 
-extension Either where B == OpenAPI.PathItem {
-    /// Retrieve the path item if that is what this property contains.
-    public var pathItemValue: B? { b }
-}
-
 // MARK: - Convenience constructors
 extension Either where A == Bool {
     /// Construct a boolean value.
@@ -152,6 +152,45 @@ extension Either where B == JSONSchema {
     public static func schema(_ schema: JSONSchema) -> Self { .b(schema) }
 }
 
+extension Either where B == OpenAPI.PathItem {
+    /// Construct a path item value.
+    public static func pathItem(_ pathItem: OpenAPI.PathItem) -> Self { .b(pathItem) }
+
+    public init(
+        summary: String? = nil,
+        description: String? = nil,
+        servers: [OpenAPI.Server]? = nil,
+        parameters: OpenAPI.Parameter.Array = [],
+        get: OpenAPI.Operation? = nil,
+        put: OpenAPI.Operation? = nil,
+        post: OpenAPI.Operation? = nil,
+        delete: OpenAPI.Operation? = nil,
+        options: OpenAPI.Operation? = nil,
+        head: OpenAPI.Operation? = nil,
+        patch: OpenAPI.Operation? = nil,
+        trace: OpenAPI.Operation? = nil,
+        vendorExtensions: [String: AnyCodable] = [:]
+    ) {
+        self = .b(
+            .init(
+                summary: summary,
+                description: description,
+                servers: servers,
+                parameters: parameters,
+                get: get,
+                put: put,
+                post: post,
+                delete: delete,
+                options: options,
+                head: head,
+                patch: patch,
+                trace: trace,
+                vendorExtensions: vendorExtensions
+            )
+        )
+    }
+}
+
 extension Either where B == OpenAPI.Parameter {
     /// Construct a parameter value.
     public static func parameter(_ parameter: OpenAPI.Parameter) -> Self { .b(parameter) }
@@ -181,8 +220,3 @@ extension Either where B == OpenAPI.Header {
     /// Construct a header value.
     public static func header(_ header: OpenAPI.Header) -> Self { .b(header) }
 }
-
-extension Either where B == OpenAPI.PathItem {
-    /// Construct a path item value.
-    public static func pathItem(_ pathItem: OpenAPI.PathItem) -> Self { .b(pathItem) }
-}

Sources/OpenAPIKit/Encoding and Decoding Errors/DocumentDecodingError.swift

@@ -16,6 +16,7 @@ extension OpenAPI.Error.Decoding {
             case path(Path)
             case inconsistency(InconsistencyError)
             case other(Swift.DecodingError)
+            case neither(EitherDecodeNoTypesMatchedError)
         }
     }
 }
@@ -31,14 +32,17 @@ extension OpenAPI.Error.Decoding.Document {
 
         case .inconsistency(let error):
             return error.subjectName
+
+        case .neither(let eitherError):
+            return eitherError.subjectName
         }
     }
 
     public var contextString: String {
         switch context {
         case .path(let pathError):
             return pathError.contextString
-        case .other, .inconsistency:
+        case .other, .inconsistency, .neither:
             return relativeCodingPathString.isEmpty
                 ? "in the root Document object"
                 : "in Document\(relativeCodingPathString)"
@@ -53,6 +57,8 @@ extension OpenAPI.Error.Decoding.Document {
             return error.errorCategory
         case .inconsistency(let error):
             return .inconsistency(details: error.details)
+        case .neither(let eitherError):
+            return eitherError.errorCategory
         }
     }
 
@@ -66,6 +72,8 @@ extension OpenAPI.Error.Decoding.Document {
                 : error.codingPath.dropLast().stringValue
         case .path(let pathError):
             return pathError.relativeCodingPathString
+        case .neither(let eitherError):
+            return eitherError.codingPath.stringValue
         }
     }
 
@@ -83,4 +91,30 @@ extension OpenAPI.Error.Decoding.Document {
         context = .path(error)
         codingPath = error.codingPath
     }
+
+    internal init(_ eitherError: EitherDecodeNoTypesMatchedError) {
+        if let eitherBranchToDigInto = Self.eitherBranchToDigInto(eitherError) {
+            self = Self(unwrapping: eitherBranchToDigInto)
+            return
+        }
+
+        context = .neither(eitherError)
+        codingPath = eitherError.codingPath
+    }
+}
+
+extension OpenAPI.Error.Decoding.Document: DiggingError {
+    public init(unwrapping error: Swift.DecodingError) {
+        if let decodingError = error.underlyingError as? Swift.DecodingError {
+            self = Self(unwrapping: decodingError)
+        } else if let inconsistencyError = error.underlyingError as? InconsistencyError {
+            self = Self(inconsistencyError)
+        } else if let pathError = error.underlyingError as? OpenAPI.Error.Decoding.Path {
+            self = Self(pathError)
+        } else if let eitherError = error.underlyingError as? EitherDecodeNoTypesMatchedError {
+            self = Self(eitherError)
+        } else {
+            self = Self(error)
+        }
+    }
 }