Requesting documentation on the <OpenApiReference /> element

[kevdev424]

[EDIT by guardrex to add the metadata]

I see a reference to <OpenApiReference /> in this document https://docs.microsoft.com/en-us/aspnet/core/web-api/microsoft.dotnet-openapi?view=aspnetcore-3.0#add but there's no real specifics as to what the settings are for it. I see ClassName OutputPath SourceUri and Options and least as sub elements but I'm not seeing any description for them, like what the full set of options are.

---

Document Details

⚠ Do not edit this section. It is required for docs.microsoft.com ➟ GitHub issue linking.

• ID: 653e14ef-227e-a165-0360-2f59259e16c6
• Version Independent ID: e4685d05-e874-76a3-9780-66b864eca6c1
• Content: Develop ASP.NET Core apps using OpenAPI
• Content Source: aspnetcore/web-api/Microsoft.dotnet-openapi.md
• Product: aspnet-core
• Technology: aspnetcore-webapi
• GitHub Login: @ryanbrandenburg
• Microsoft Alias: rybrande

[guardrex]

Hello @kthayer424 It's best if you open issues from the This Page feedback button/form at the bottom of the topic. It automatically pings the author. I'll add the metadata to your opening remark.

[scottaddie]

@bradygaster or @dougbu, do either of you have any info on this?

[dougbu]

@scottaddie and @kthayer424 @(OpenApiReference) items are part of the infrastructure used in Visual Studio 2019's Service References feature (part of Connected Services) and the dotnet openapi tool described at https://docs.microsoft.com/en-us/aspnet/core/web-api/microsoft.dotnet-openapi?view=aspnetcore-3.1

While it is possible to manually add @(OpenApiReference) items and some configuration properties to your projects, we have not yet documented this infrastructure. If I remember correctly, #8462 is the (long-standing, sorry) issue about providing such documentation.

I do not personally have time to do this work and am heading off soon for end-of-year vacation. But that doesn't mean we're satisfied with this gap.

Over to you @bradygaster

[SimonCull]

Has there been any update on this?

[bradygaster]

We've not made any progress on this doc update yet but we have been investing in other areas where OAS is valuable to customers (and to us) so this is getting picked up and prioritized more efficiently now. I'll work with the team to escalate the attention we're giving this. Apologies in advance.

[jkone27]

any updates? I am pushing to adopt this, but documentation would be much appreciated 👍 awesome feature by the way.

[stevetalkscode]

Hopefully my blog post that I have published today goes some way to filling the documentation gap https://stevetalkscode.co.uk/openapireference-commands

If an official Microsoft Docs area is started, happy to contribute the content from the blog post to it

[bradygaster]

This is excellent, @stevetalkscode. I'll review it in more detail and think about how it could be included, as I think it'd be valuable at first glance. Curious if @scottaddie has any thoughts on this, or if @dougbu has thoughts. I'd imagine this doc is where we'd want to mix it in.

https://docs.microsoft.com/en-us/aspnet/core/web-api/microsoft.dotnet-openapi?view=aspnetcore-5.0

[stevetalkscode]

Thanks @bradygaster. Glad it goes some way to doing the job.

[Rick-Anderson]

@bradygaster we should take advantage of this offer.

[bradygaster]

@Rick-Anderson i think that's basically what i said up above. Do we have a next step?

[Rick-Anderson]

@Rick-Anderson i think that's basically what i said up above. Do we have a next step?

@bradygaster you could outline what you want transferred from @stevetalkscode blog to this doc, then @stevetalkscode could do a PR and you could review it.