mattpolzin
commented
1 year ago Upon more reflection, I think there's not much need for the above strategy to support both inlining of remote references and also storing them in the components object; inlining could be accomplished by first loading remote references into components and then as a second step calling the existing locally dereferencing code to inline things from the components object. This would be the case for all refs except path items in v3.0.x of the spec -- they need to be inlined straight off because path items cannot be stored in the components object prior to v3.1.x of the spec.
As discussed here: https://github.com/apple/swift-openapi-generator/issues/25.
I think I am starting to solidify an idea for this via a new method on a document (also exposed directly on OpenAPI/JSON references); we'll call it
loadExternalReferences()for now. This function would take as input another function (a handler) that takes a path as input (details about local vs. remote paths TBD) and returns a decoded OpenAPIKit type. The exact OpenAPIKit type it returns would be parameterized.loadExternalReferences()would then use that function to load in all external references on the Document and return a new Document where the references are replaced by either an inlined OpenAPIKit value or (probably based on a configuration setting) stored in the Components object and therefore transformed from an external to an internal reference.One random implementation detail that comes to mind is storing the external file path used when loading something into a newly combined document as a vendor extension on the newly inlined value or localized reference -- I would need to confirm that all objects that can be referenced also support vendor extensions (I already know this would require adding support for vendor extensions to JSON Schemas, a long-standing todo item).