Include Github link to OpenApi Tool Readme

[OzBob]

My suggestion:, add an example of how to configure the csproj node setting to 'on build' generate an openapi file that SwaggerUI could use, NSwag could use to generate a 'connected client'.

Also, the github repo for Microsoft.dotnet-openapi is the 'dotnet aspnetcore' repo, it is quite big, so to assist the reader in finding an example and further guidance on configuring the entry in the csproj file, add a link to:

https://github.com/dotnet/aspnetcore/blob/main/src/Tools/Microsoft.dotnet-openapi/README.md

The contents seem to have been copy and pasted in this doc page, are they auto updated when the readme is updated?

NSwag generates a client onBuild by Rico Suter

<Target Name="NSwag" AfterTargets="Build">
    <Exec EnvironmentVariables="ASPNETCORE_ENVIRONMENT=Development" Command="$(NSwagExe) aspnetcore2openapi /assembly:$(TargetDir)MyWebAssembly.dll /output:swagger.json" />
    <Exec Command="$(NSwagExe) openapi2tsclient /input:swagger.json /output:Scripts/MyController.ts" />
</Target>

And example of .csproj connected client using the generated .json by Jon Galoway:

<ItemGroup>
  <OpenApiReference Include="..\ContosoOnlineOrders.Api\bin\Debug\net5.0\ContosoOnlineOrders.Api.json" Namespace="ContosoOnlineOrders.ConsoleClient">
    <Link>OpenAPIs\ContosoOnlineOrders.Api.json</Link>
  </OpenApiReference>
</ItemGroup>

I have not found a blog post (not even Brady Gaster's: https://devblogs.microsoft.com/aspnet/creating-discoverable-http-apis-with-asp-net-core-5-web-api/?WT.mc_id=dotnet-13135-bradyg), so I'd really appreciate a complete example of using the openapi tool.

The new 'Microsoft.dotnet-openapi' example could also be used to improve the readme doc :-)

---

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

[ryanbrandenburg]

CC @mkArtakMSFT to re-assign to the new owner.

[rafikiassumani-msft]

@captainsafia, we have the following issue requesting documentation on the OpenApi https://github.com/dotnet/AspNetCore.Docs/issues/15899. Let's consider documenting this for net7 release. Any thoughts ?

[captainsafia]

Making a page similar to what we did for dotnet user-jwt might help here. I think the tool in-and-off itself is not meaningful to document since it is primarily responsible for updating the csproj with the OpenApiReferences (in fact people can write these properties directly themselves). It probably makes sense to document it alongside info about how it plugs into code generation with visual studio or NSwag.

Let's consider documenting this for net7 release.

We can, although I think the documentation should be for versions 3.1 through 7.0 since this isn't a new tool.

Edit: I've added this as a task under https://github.com/dotnet/aspnetcore/issues/44257.