Merge pull request #295 from mattpolzin/store-dereferenced-component-name

store component name as x-component-name when locally dereferencing an object.

Author: mattpolzin

README.md

@@ -228,6 +228,8 @@ Unlike what happens when you lookup an individual component using the `lookup()`
 
 Anywhere that a type would have had either a reference or a component, the dereferenced variety will simply have the component. For example, `PathItem` has an array of parameters, each of which is `Either<JSONReference<Parameter>, Parameter>` whereas a `DereferencedPathItem` has an array of `DereferencedParameter`s. The dereferenced variant of each type exposes all the same properties and you can get at the underlying `OpenAPI` type via an `underlying{TypeName}` property. This can make for a much more convenient way to traverse a document because you don't need to check for or look up references anywhere the OpenAPI Specification allows them.
 
+For all dereferenced types except for `JSONSchema`, dereferencing will store a new vendor extension on the dereferenced value to keep track of the Component Object name the value used to be referenced at. This vendor extension is a string value with the `x-component-name` key.
+
 You can take things a step further and resolve the document. Calling `resolved()` on a `DereferencedDocument` will produce a canonical form of an `OpenAPI.Document`. The `ResolvedRoute`s and `ResolvedEndpoint`s that the `ResolvedDocument` exposes collect all relevant information from the whole document into themselves. For example, a `ResolvedEndpoint` knows what servers it can be used on, what path it is located at, and which parameters it supports (even if some of those parameters were defined in an `OpenAPI.Operation` and others were defined in the containing `OpenAPI.PathItem`).
 
 If your end goal is to analyze the OpenAPI Document or generate something entirely new (like code) from it, the `ResolvedDocument` is by far more convenient to traverse and query than the original `OpenAPI.Document`. The downside is, there is not currently support for mutating the `ResolvedDocument` and then turning it back into an `OpenAPI.Document` to encode it.

Sources/OpenAPIKit/Components Object/Components+Locatable.swift

@@ -85,13 +85,18 @@ public protocol LocallyDereferenceable {
     /// For all external-use, see `dereferenced(in:)` (provided by the `LocallyDereferenceable` protocol).
     /// All types that provide a `_dereferenced(in:following:)` implementation have a `dereferenced(in:)`
     /// implementation for free.
-    func _dereferenced(in components: OpenAPI.Components, following references: Set<AnyHashable>) throws -> DereferencedSelf
+    func _dereferenced(
+        in components: OpenAPI.Components,
+        following references: Set<AnyHashable>,
+        dereferencedFromComponentNamed name: String?
+    ) throws -> DereferencedSelf
 }
 
 extension LocallyDereferenceable {
     // default implementation of public `dereferenced(in:)` based on internal
     // method that tracks reference cycles.
     public func dereferenced(in components: OpenAPI.Components) throws -> DereferencedSelf {
-        try _dereferenced(in: components, following: [])
+        try _dereferenced(in: components, following: [], dereferencedFromComponentNamed: nil)
     }
 }
+

Sources/OpenAPIKit/Components Object/Components.swift

@@ -66,6 +66,14 @@ extension OpenAPI {
     }
 }
 
+extension OpenAPI.Components {
+    /// The extension name used to store a Components Object name (the key something is stored under
+    /// within the Components Object). This is used by OpenAPIKit to store the previous Component name 
+    /// of an OpenAPI Object that has been dereferenced (pulled out of the Components and stored inline
+    /// in the OpenAPI Document).
+    public static let componentNameExtension: String = "x-component-name"
+}
+
 extension OpenAPI {
     /// A key for one of the component dictionaries.
     ///

Sources/OpenAPIKit/Content/DereferencedContent.swift

@@ -32,16 +32,23 @@ public struct DereferencedContent: Equatable {
         resolvingIn components: OpenAPI.Components,
         following references: Set<AnyHashable>
     ) throws {
-        self.schema = try content.schema?._dereferenced(in: components, following: references)
-        let examples = try content.examples?.mapValues { try components.lookup($0) }
+        self.schema = try content.schema?._dereferenced(in: components, following: references, dereferencedFromComponentNamed: nil)
+        let examples = try content.examples?
+            .mapValues { 
+                try $0._dereferenced(
+                    in: components, 
+                    following: references, 
+                    dereferencedFromComponentNamed: nil
+                )
+            }
         self.examples = examples
 
         self.example = examples.flatMap(OpenAPI.Content.firstExample(from:))
             ?? content.example
 
         self.encoding = try content.encoding.map { encodingMap in
             try encodingMap.mapValues { encoding in
-                try encoding._dereferenced(in: components, following: references)
+                try encoding._dereferenced(in: components, following: references, dereferencedFromComponentNamed: nil)
             }
         }
 
@@ -58,7 +65,11 @@ extension OpenAPI.Content: LocallyDereferenceable {
     /// For all external-use, see `dereferenced(in:)` (provided by the `LocallyDereferenceable` protocol).
     /// All types that provide a `_dereferenced(in:following:)` implementation have a `dereferenced(in:)`
     /// implementation for free.
-    public func _dereferenced(in components: OpenAPI.Components, following references: Set<AnyHashable>) throws -> DereferencedContent {
+    public func _dereferenced(
+        in components: OpenAPI.Components,
+        following references: Set<AnyHashable>,
+        dereferencedFromComponentNamed name: String?
+    ) throws -> DereferencedContent {
         return try DereferencedContent(self, resolvingIn: components, following: references)
     }
 }

Sources/OpenAPIKit/Content/DereferencedContentEncoding.swift

@@ -31,7 +31,7 @@ public struct DereferencedContentEncoding: Equatable {
     ) throws {
         self.headers = try contentEncoding.headers.map { headersMap in
             try headersMap.mapValues { header in
-                try header._dereferenced(in: components, following: references)
+                try header._dereferenced(in: components, following: references, dereferencedFromComponentNamed: nil)
             }
         }
 
@@ -46,7 +46,11 @@ extension OpenAPI.Content.Encoding: LocallyDereferenceable {
     /// For all external-use, see `dereferenced(in:)` (provided by the `LocallyDereferenceable` protocol).
     /// All types that provide a `_dereferenced(in:following:)` implementation have a `dereferenced(in:)`
     /// implementation for free.
-    public func _dereferenced(in components: OpenAPI.Components, following references: Set<AnyHashable>) throws -> DereferencedContentEncoding {
+    public func _dereferenced(
+        in components: OpenAPI.Components,
+        following references: Set<AnyHashable>,
+        dereferencedFromComponentNamed name: String?
+    ) throws -> DereferencedContentEncoding {
         return try DereferencedContentEncoding(self, resolvingIn: components, following: references)
     }
 }

Sources/OpenAPIKit/Document/DereferencedDocument.swift

@@ -50,7 +50,8 @@ public struct DereferencedDocument: Equatable {
             try DereferencedPathItem(
                 $0,
                 resolvingIn: document.components,
-                following: []
+                following: [],
+                dereferencedFromComponentNamed: nil
             )
         }
         self.security = try document.security.map {

Sources/OpenAPIKit/Either/Either.swift

@@ -58,12 +58,16 @@ extension Either: Equatable where A: Equatable, B: Equatable {}
 
 // MARK: - LocallyDereferenceable
 extension Either: LocallyDereferenceable where A: LocallyDereferenceable, B: LocallyDereferenceable, A.DereferencedSelf == B.DereferencedSelf {
-    public func _dereferenced(in components: OpenAPI.Components, following references: Set<AnyHashable>) throws -> A.DereferencedSelf {
+    public func _dereferenced(
+        in components: OpenAPI.Components,
+        following references: Set<AnyHashable>,
+        dereferencedFromComponentNamed name: String?
+    ) throws -> A.DereferencedSelf {
         switch self {
         case .a(let value):
-            return try value._dereferenced(in: components, following: references)
+            return try value._dereferenced(in: components, following: references, dereferencedFromComponentNamed: nil)
         case .b(let value):
-            return try value._dereferenced(in: components, following: references)
+            return try value._dereferenced(in: components, following: references, dereferencedFromComponentNamed: nil)
         }
     }
 }

Sources/OpenAPIKit/Example.swift

@@ -158,8 +158,22 @@ extension OpenAPI.Example {
 extension OpenAPI.Example: LocallyDereferenceable {
     /// Examples do not contain any references but for convenience
     /// they can be "dereferenced" to themselves.
-    public func _dereferenced(in components: OpenAPI.Components, following references: Set<AnyHashable>) throws -> OpenAPI.Example {
-        return self
+    public func _dereferenced(
+        in components: OpenAPI.Components,
+        following references: Set<AnyHashable>,
+        dereferencedFromComponentNamed name: String?
+    ) throws -> OpenAPI.Example{
+        var vendorExtensions = self.vendorExtensions
+        if let name = name {
+            vendorExtensions[OpenAPI.Components.componentNameExtension] = .init(name)
+        }
+
+        return .init(
+            summary: self.summary,
+            description: self.description,
+            value: self.value,
+            vendorExtensions: vendorExtensions
+        )
     }
 }
 

Sources/OpenAPIKit/Header/DereferencedHeader.swift

@@ -30,7 +30,8 @@ public struct DereferencedHeader: Equatable {
     internal init(
         _ header: OpenAPI.Header,
         resolvingIn components: OpenAPI.Components,
-        following references: Set<AnyHashable>
+        following references: Set<AnyHashable>,
+        dereferencedFromComponentNamed name: String?
     ) throws {
         switch header.schemaOrContent {
         case .a(let schemaContext):
@@ -53,6 +54,11 @@ public struct DereferencedHeader: Equatable {
             )
         }
 
+        var header = header
+        if let name = name {
+            header.vendorExtensions[OpenAPI.Components.componentNameExtension] = .init(name)
+        }
+
         self.underlyingHeader = header
     }
 
@@ -66,7 +72,11 @@ extension OpenAPI.Header: LocallyDereferenceable {
     /// For all external-use, see `dereferenced(in:)` (provided by the `LocallyDereferenceable` protocol).
     /// All types that provide a `_dereferenced(in:following:)` implementation have a `dereferenced(in:)`
     /// implementation for free.
-    public func _dereferenced(in components: OpenAPI.Components, following references: Set<AnyHashable>) throws -> DereferencedHeader {
-        return try DereferencedHeader(self, resolvingIn: components, following: references)
+    public func _dereferenced(
+        in components: OpenAPI.Components,
+        following references: Set<AnyHashable>,
+        dereferencedFromComponentNamed name: String?
+    ) throws -> DereferencedHeader {
+        return try DereferencedHeader(self, resolvingIn: components, following: references, dereferencedFromComponentNamed: name)
     }
 }

Sources/OpenAPIKit/JSONReference.swift

@@ -358,8 +358,11 @@ extension JSONReference: LocallyDereferenceable where ReferenceType: LocallyDere
     ///
     /// If you just want to look the reference up, use the `subscript` or the
     /// `lookup()` method on `Components`.
-    public func _dereferenced(in components: OpenAPI.Components, following references: Set<AnyHashable>) throws -> ReferenceType.DereferencedSelf {
-
+    public func _dereferenced(
+        in components: OpenAPI.Components,
+        following references: Set<AnyHashable>,
+        dereferencedFromComponentNamed name: String?
+    ) throws -> ReferenceType.DereferencedSelf {
         var newReferences = references
         let (inserted, _) = newReferences.insert(self)
         guard inserted else {
@@ -368,7 +371,7 @@ extension JSONReference: LocallyDereferenceable where ReferenceType: LocallyDere
 
         return try components
             .lookup(self)
-            ._dereferenced(in: components, following: newReferences)
+            ._dereferenced(in: components, following: newReferences, dereferencedFromComponentNamed: self.name)
     }
 }
 

Sources/OpenAPIKit/Operation/DereferencedOperation.swift

@@ -50,15 +50,15 @@ public struct DereferencedOperation: Equatable {
         following references: Set<AnyHashable>
     ) throws {
         self.parameters = try operation.parameters.map { parameter in
-            try parameter._dereferenced(in: components, following: references)
+            try parameter._dereferenced(in: components, following: references, dereferencedFromComponentNamed: nil)
         }
 
         self.requestBody = try operation.requestBody.map { request in
-            try request._dereferenced(in: components, following: references)
+            try request._dereferenced(in: components, following: references, dereferencedFromComponentNamed: nil)
         }
 
         self.responses = try operation.responses.mapValues { response in
-            try response._dereferenced(in: components, following: references)
+            try response._dereferenced(in: components, following: references, dereferencedFromComponentNamed: nil)
         }
 
         self.security = try operation.security?.map {
@@ -105,7 +105,11 @@ extension OpenAPI.Operation: LocallyDereferenceable {
     /// For all external-use, see `dereferenced(in:)` (provided by the `LocallyDereferenceable` protocol).
     /// All types that provide a `_dereferenced(in:following:)` implementation have a `dereferenced(in:)`
     /// implementation for free.
-    public func _dereferenced(in components: OpenAPI.Components, following references: Set<AnyHashable>) throws -> DereferencedOperation {
+    public func _dereferenced(
+        in components: OpenAPI.Components,
+        following references: Set<AnyHashable>,
+        dereferencedFromComponentNamed name: String?
+    ) throws -> DereferencedOperation {
         return try DereferencedOperation(self, resolvingIn: components, following: references)
     }
 }

Sources/OpenAPIKit/Parameter/DereferencedParameter.swift

@@ -32,7 +32,8 @@ public struct DereferencedParameter: Equatable {
     internal init(
         _ parameter: OpenAPI.Parameter,
         resolvingIn components: OpenAPI.Components,
-        following references: Set<AnyHashable>
+        following references: Set<AnyHashable>,
+        dereferencedFromComponentNamed name: String?
     ) throws {
         switch parameter.schemaOrContent {
         case .a(let schemaContext):
@@ -55,6 +56,11 @@ public struct DereferencedParameter: Equatable {
             )
         }
 
+        var parameter = parameter
+        if let name = name {
+            parameter.vendorExtensions[OpenAPI.Components.componentNameExtension] = .init(name)
+        }
+
         self.underlyingParameter = parameter
     }
 }
@@ -66,7 +72,11 @@ extension OpenAPI.Parameter: LocallyDereferenceable {
     /// For all external-use, see `dereferenced(in:)` (provided by the `LocallyDereferenceable` protocol).
     /// All types that provide a `_dereferenced(in:following:)` implementation have a `dereferenced(in:)`
     /// implementation for free.
-    public func _dereferenced(in components: OpenAPI.Components, following references: Set<AnyHashable>) throws -> DereferencedParameter {
-        return try DereferencedParameter(self, resolvingIn: components, following: references)
+    public func _dereferenced(
+        in components: OpenAPI.Components,
+        following references: Set<AnyHashable>,
+        dereferencedFromComponentNamed name: String?
+    ) throws -> DereferencedParameter {
+        return try DereferencedParameter(self, resolvingIn: components, following: references, dereferencedFromComponentNamed: name)
     }
 }

Sources/OpenAPIKit/Parameter/DereferencedSchemaContext.swift

@@ -40,7 +40,7 @@ public struct DereferencedSchemaContext: Equatable {
         resolvingIn components: OpenAPI.Components,
         following references: Set<AnyHashable>
     ) throws {
-        self.schema = try schemaContext.schema._dereferenced(in: components, following: references)
+        self.schema = try schemaContext.schema._dereferenced(in: components, following: references, dereferencedFromComponentNamed: nil)
         let examples = try schemaContext.examples?.mapValues { try components.lookup($0) }
         self.examples = examples
 
@@ -58,7 +58,11 @@ extension OpenAPI.Parameter.SchemaContext: LocallyDereferenceable {
     /// For all external-use, see `dereferenced(in:)` (provided by the `LocallyDereferenceable` protocol).
     /// All types that provide a `_dereferenced(in:following:)` implementation have a `dereferenced(in:)`
     /// implementation for free.
-    public func _dereferenced(in components: OpenAPI.Components, following references: Set<AnyHashable>) throws -> DereferencedSchemaContext {
+    public func _dereferenced(
+        in components: OpenAPI.Components,
+        following references: Set<AnyHashable>,
+        dereferencedFromComponentNamed name: String?
+    ) throws -> DereferencedSchemaContext {
         return try DereferencedSchemaContext(self, resolvingIn: components, following: references)
     }
 }

Sources/OpenAPIKit/Path Item/DereferencedPathItem.swift

@@ -46,10 +46,11 @@ public struct DereferencedPathItem: Equatable {
     internal init(
         _ pathItem: OpenAPI.PathItem,
         resolvingIn components: OpenAPI.Components,
-        following references: Set<AnyHashable>
+        following references: Set<AnyHashable>,
+        dereferencedFromComponentNamed name: String?
     ) throws {
         self.parameters = try pathItem.parameters.map { parameter in
-            try parameter._dereferenced(in: components, following: references)
+            try parameter._dereferenced(in: components, following: references, dereferencedFromComponentNamed: nil)
         }
 
         self.get = try pathItem.get.map { try DereferencedOperation($0, resolvingIn: components, following: references) }
@@ -61,6 +62,11 @@ public struct DereferencedPathItem: Equatable {
         self.patch = try pathItem.patch.map { try DereferencedOperation($0, resolvingIn: components, following: references) }
         self.trace = try pathItem.trace.map { try DereferencedOperation($0, resolvingIn: components, following: references) }
 
+        var pathItem = pathItem
+        if let name = name {
+            pathItem.vendorExtensions[OpenAPI.Components.componentNameExtension] = .init(name)
+        }
+
         self.underlyingPathItem = pathItem
     }
 
@@ -121,7 +127,11 @@ extension OpenAPI.PathItem: LocallyDereferenceable {
     /// For all external-use, see `dereferenced(in:)` (provided by the `LocallyDereferenceable` protocol).
     /// All types that provide a `_dereferenced(in:following:)` implementation have a `dereferenced(in:)`
     /// implementation for free.
-    public func _dereferenced(in components: OpenAPI.Components, following references: Set<AnyHashable>) throws -> DereferencedPathItem {
-        return try DereferencedPathItem(self, resolvingIn: components, following: references)
+    public func _dereferenced(
+        in components: OpenAPI.Components,
+        following references: Set<AnyHashable>,
+        dereferencedFromComponentNamed name: String?
+    ) throws -> DereferencedPathItem {
+        return try DereferencedPathItem(self, resolvingIn: components, following: references, dereferencedFromComponentNamed: name)
     }
 }