How to load external referenced fragments/documents?

[Egil Hansen (egil)]

I have the following two documents:

Demo-API.v1.yaml

openapi: 3.0.0info:
title: Demo APIversion: '1.0'servers:
- url: /paths:
/:
get:
summary: Your GET endpointtags: []responses:
'200':
description: OKcontent:
application/json:
schema:
type: stringoperationId: get-hiparameters:
- schema:
type: stringin: queryname: message/ping:
get:
summary: Your GET endpointtags: []responses:
'200':
description: OKcontent:
application/json:
schema:
type: stringoperationId: get-ping/pong:
$ref: './Paths.v1.yaml#/pong'components:
schemas: {}

Paths.v1.yaml

pong:
get:
summary: Your GET endpointtags: []responses:
'200':
description: OKcontent:
application/json:
schema:
type: string

Both files are in the same folder, but I cannot get the OpenApiStreamReader to load the content of Paths.v1.yaml into the Demo-API.v1.yaml document. My latest attempt looks like this:

varopenApiReader=newOpenApiStreamReader(newOpenApiReaderSettings{BaseUrl=newUri("file://C:\\source\\temp\\ConsoleApp1\\ConsoleApp1\\reference"),ReferenceResolution=ReferenceResolutionSetting.ResolveAllReferences,});varreadResult=awaitopenApiReader.ReadAsync(File.OpenRead(@"C:\\source\\temp\\ConsoleApp1\\ConsoleApp1\\reference\\Demo-API.v1.yaml"));

However, the content of the pong path item has UnresolvedReference: true and is otherwise empty.

What am I missing here?

Version: 1.3.0-preview as well as the sources locally on my machine.
.NET: 6

[Darrel (darrelmiller)]

The code to make this happen is still work in progress. If when you write out the result you set it to inline, the results, it should include the referenced file in the output. I'm hoping to get this fixed in the next couple of weeks.

[Egil Hansen (egil)]

Thanks for getting back to me. Just want to verify that I understand what you write:

The resulting OpenApiDocument will work and look as if both the "root" document as well as any referenced fragments/documents all came from the same document, and, if I want, I can actually do a ToString on it to get a combined document printed out?

Will this also work with absolute references, e.g. to URLs on the internet? If yes, it would be great if this could be enabled/disabled through options/configuration. We have seen recently that blindly resolving remote URLs can be a security risk (log4j).

[Darrel (darrelmiller)]

In order to automatically load external references you must set the ResolveAllReferences and use LoadAsync. It will only load HTTP/HTTPS urls and will parse them as JSON/YAML. It is not possible to trigger arbitrary code execution as we do not deserialize YAML into native types. Only into YAML primitives.

In order to write out externally referenced documents, you need to use the OpenApiWriter and set the ReferenceInline property on the settings to ReferenceInline.

I am currently testing these scenarios and this use case should work when 1.3.0 is released.

[Egil Hansen (egil)]

Very good.

Will external references inside other external references also be loaded, or is it only one level deep?