Creates component registries in the `OpenApiWorkspace` for `$ref` resolution #1609

irvinesunday · 2024-04-02T13:00:48Z

Fixes #805

This PR:

Updates the OpenApiWorkspace.cs class by adding components registries that store JsonSchemas (or fragments), IOpenApiReferenceable objects and stream artifacts. These are indexed with unique key identifiers (URIs) that are a component of the unique document id that the components exist or as provided (in the case of stream artifacts or JsonSchema fragments). These unique key identifiers are also used to fetch the components from the components registry in the OpenApiWorkspace. The format of the URI identifier will be of the format:
ex: http://openapi.net/{documentId}/components/schema/{name}
OpenApiWorkspaces are instantiated in the constructors of OpenApiDocuments. The document's BaseUri property is also instantiated in the constructor and is composed of the base path http://openapi.net/ and the unique document Id, which is a GUID.
All reference resolution (local and external) now happens in the workspace of the entry level OpenApiDocument. External documents have their ExternalResource identifier registered together with the unique document id of their host document in a _documentsIdRegister. This is a look-up table that external ref resolution uses to look up the unique document ids of external documents, given an ExternalResource identifier in an OpenApiReference object. This document id extracted from the lookup table will be used alongside the base path and the reference object id to construct the unique URI key that will be used to fetch the resolved component from the workspace component registry.

…-registry

src/Microsoft.OpenApi/Models/OpenApiDocument.cs

src/Microsoft.OpenApi/Services/OpenApiWorkspace.cs

src/Microsoft.OpenApi/Reader/Services/OpenApiRemoteReferenceCollector.cs

…tion

src/Microsoft.OpenApi/Models/OpenApiDocument.cs

+        public OpenApiDocument() 
+        {
+            Workspace = new OpenApiWorkspace();
+            BaseUri = new(OpenApiConstants.BaseRegistryUri + Guid.NewGuid().ToString());            


src/Microsoft.OpenApi/Services/OpenApiWorkspace.cs

+            else if (component is Stream stream)
+            {
+                if (!_artifactsRegistry.ContainsKey(uri))
+                {
+                    _artifactsRegistry[uri] = stream;
+                    return true;
+                }
+            }


src/Microsoft.OpenApi/Services/OpenApiWorkspace.cs

-                    return resolver.ResolveJsonSchemaReference(reference);
-                }
-                return null;
+                return (T)(object)artifact;


darrelmiller · 2024-04-03T04:11:33Z

src/Microsoft.OpenApi/Services/OpenApiWorkspace.cs

@@ -62,7 +39,7 @@ public OpenApiWorkspace(Uri baseUrl)
        /// </summary>
        public OpenApiWorkspace()
        {
-            BaseUrl = new("file://" + Environment.CurrentDirectory + $"{Path.DirectorySeparatorChar}" );
+            BaseUrl = new Uri(OpenApiConstants.BaseRegistryUri);


I'm fighting with the feeling that "it can't be this simple", but if every document gets it's own GUID in the baseURI then we really don't need to use a file path. I think this is really good.

darrelmiller

I can't say I have been able to mentally compile every line of this, but I really like the way this is looking. We need to get this merged with Maggie's changes and then do some extensive testing on it.

src/Microsoft.OpenApi/Models/OpenApiExample.cs

@@ -68,7 +68,7 @@
        {
            Summary = example?.Summary ?? Summary;
            Description = example?.Description ?? Description;
-            Value = JsonNodeCloneHelper.Clone(example?.Value);
+            Value = example?.Value ?? JsonNodeCloneHelper.Clone(example?.Value);


src/Microsoft.OpenApi/Models/OpenApiHeader.cs

@@ -114,8 +114,8 @@
            Style = header?.Style ?? Style;
            Explode = header?.Explode ?? Explode;
            AllowReserved = header?.AllowReserved ?? AllowReserved;
-            _schema = JsonNodeCloneHelper.CloneJsonSchema(header?.Schema);
-            Example = JsonNodeCloneHelper.Clone(header?.Example);
+            Schema = header?.Schema != null ? JsonNodeCloneHelper.CloneJsonSchema(header?.Schema) : null;


src/Microsoft.OpenApi/Models/OpenApiHeader.cs

-            _schema = JsonNodeCloneHelper.CloneJsonSchema(header?.Schema);
-            Example = JsonNodeCloneHelper.Clone(header?.Example);
+            Schema = header?.Schema != null ? JsonNodeCloneHelper.CloneJsonSchema(header?.Schema) : null;
+            Example = header?.Example != null ? JsonNodeCloneHelper.Clone(header?.Example) : null;


src/Microsoft.OpenApi/Models/OpenApiParameter.cs

@@ -167,9 +167,9 @@
            Style = parameter?.Style ?? Style;
            Explode = parameter?.Explode ?? Explode;
            AllowReserved = parameter?.AllowReserved ?? AllowReserved;
-            _schema = JsonNodeCloneHelper.CloneJsonSchema(parameter?.Schema);
+            Schema = parameter?.Schema != null ? JsonNodeCloneHelper.CloneJsonSchema(parameter?.Schema) : null;


src/Microsoft.OpenApi/Models/OpenApiParameter.cs

            Examples = parameter?.Examples != null ? new Dictionary<string, OpenApiExample>(parameter.Examples) : null;
-            Example = JsonNodeCloneHelper.Clone(parameter?.Example);
+            Example = parameter?.Example != null ? JsonNodeCloneHelper.Clone(parameter?.Example) : null;


src/Microsoft.OpenApi/Models/OpenApiExample.cs

@@ -68,7 +68,7 @@
        {
            Summary = example?.Summary ?? Summary;
            Description = example?.Description ?? Description;
-            Value = JsonNodeCloneHelper.Clone(example?.Value);
+            Value = example?.Value ?? JsonNodeCloneHelper.Clone(example?.Value);


…-registry

irvinesunday added 25 commits March 5, 2024 15:23

Add methods to set and retrieve components registries

ce5c724

Create new property that will capture unique document ID or base Uri

94028ae

Update workspace

e27a4e8

Update reference resolver tests

95710e5

Register components in document deserializers

76512a2

Add document to its workspace when created via parameterless constructor

4bd1685

Use document Workspace instance

5cea77e

Use the document Workspace instance already created in the ctor

351baec

Don't register components directly

a5af833

Remove ref resolution from doc.; update ctor

8acb0d2

Update workspace; add new methods

2cfaf7a

Update tests

9bdbac6

Merge remote-tracking branch 'origin/release/2.0.0' into is/component…

74e4b4d

…-registry

Add JsonSchema reference resolution to OpenApiDocument class

dd3f13c

Remove unnecessary code; revert BaseUrl value

0e3bf94

Update tests

276e5ee

Remove unused code

14597de

Revert deleted code

ea186d8

Update reference test

6ebc492

Update test

4f09473

Update test file and test

4e480ed

Update models

1b286e5

Update tests

e7ff360

Update Public Api

ef633cf

Resolve public Api

dbfcf0a

irvinesunday requested review from darrelmiller, peombwa, zengin, baywet and millicentachieng as code owners April 2, 2024 13:00

irvinesunday requested review from MaggieKimani1 and andrueastman as code owners April 2, 2024 13:00

github-advanced-security bot found potential problems Apr 2, 2024

View reviewed changes

Register local refs within external documents with unique GUID

464bd21

github-advanced-security bot found potential problems Apr 2, 2024

View reviewed changes

src/Microsoft.OpenApi/Reader/Services/OpenApiRemoteReferenceCollector.cs Fixed Show fixed Hide fixed

Refactor functions

77d1e49

github-advanced-security bot found potential problems Apr 2, 2024

View reviewed changes

src/Microsoft.OpenApi/Reader/Services/OpenApiRemoteReferenceCollector.cs Fixed Show fixed Hide fixed

irvinesunday marked this pull request as draft April 2, 2024 14:08

Use unique document ids in URIs in components registry and ref resolu…

9a9827a

…tion

github-advanced-security bot found potential problems Apr 3, 2024

View reviewed changes

irvinesunday changed the title ~~Uses the document workspace to resolve local and external references~~ Creates component registries in the OpenApiWorkspace for $ref resolution Apr 3, 2024

darrelmiller reviewed Apr 3, 2024

View reviewed changes

darrelmiller approved these changes Apr 3, 2024

View reviewed changes

irvinesunday marked this pull request as ready for review April 3, 2024 08:11

irvinesunday self-assigned this Apr 3, 2024

irvinesunday added 3 commits April 4, 2024 02:37

Merge branch release/2.0.0

feb674f

Remove unnecessary code

6954790

Resolve merge conflicts with release/2.0.0 branch

f6912ab

github-advanced-security bot found potential problems Apr 4, 2024

View reviewed changes

irvinesunday added 6 commits April 4, 2024 19:04

Merge method resolving JsonSchemas with SetHostDocument

33236ad

Update XML summary

977e8c6

Update PublicAPI

21bed6b

Merge remote-tracking branch 'origin/release/2.0.0' into is/component…

d744e64

…-registry

Update Public API

54712c1

Update comment

11b3399

irvinesunday requested a review from darrelmiller April 4, 2024 19:49

darrelmiller approved these changes Apr 5, 2024

View reviewed changes

irvinesunday merged commit 77cd25a into release/2.0.0 Apr 5, 2024
5 of 8 checks passed

irvinesunday deleted the is/component-registry branch April 5, 2024 08:09

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Creates component registries in the `OpenApiWorkspace` for `$ref` resolution #1609

Creates component registries in the `OpenApiWorkspace` for `$ref` resolution #1609

irvinesunday commented Apr 2, 2024 •

edited

Loading

darrelmiller Apr 3, 2024

darrelmiller left a comment

Creates component registries in the OpenApiWorkspace for $ref resolution #1609

Creates component registries in the OpenApiWorkspace for $ref resolution #1609

Conversation

irvinesunday commented Apr 2, 2024 • edited Loading

darrelmiller Apr 3, 2024

Choose a reason for hiding this comment

darrelmiller left a comment

Choose a reason for hiding this comment

Creates component registries in the `OpenApiWorkspace` for `$ref` resolution #1609

Creates component registries in the `OpenApiWorkspace` for `$ref` resolution #1609

irvinesunday commented Apr 2, 2024 •

edited

Loading