search

dotnet / AspNetCore.Docs

Documentation for ASP.NET Core
https://docs.microsoft.com/aspnet/core
Creative Commons Attribution 4.0 International
12.56k stars 25.3k forks source link

Include Github link to OpenApi Tool Readme #22176

Open OzBob opened 3 years ago

OzBob commented 3 years ago

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.

ryanbrandenburg commented 3 years ago

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

rafikiassumani-msft commented 1 year ago

@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 commented 1 year ago

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.