In a previous ASP.NET Core Web API Tutorial, I mentioned how the new ASP.NET Core Web API Project Template for .NET 5 Framework includes the addition of Swashbuckle.AspNetCore to generate an OpenAPI Specification Document as well as a Swagger UI to explore and test the web API. This works in tandem with a new feature introduced in Visual Studio 2019 that allows you to publish the web API to Azure API Management Services as part of the flow of publishing the ASP.NET Core Web API. Of course, you have the option to opt-out of publishing to Azure API Management Services, and the ASP.NET Core Web API publish flow is smart enough to detect if you aren't using Swashbuckle to generate an OpenAPI Specification Document as well. In this tutorial, I am mainly showing the new OpenAPI feature that I talked about in much more depth in the previous tutorial mentioned above.
Visual Studio 2019 Create ASP.NET Core Web API
When creating a new ASP.NET Core Web API in Visual Studio 2019 you now have the option of including OpenAPI support.
OpenAPI support is enabled by default when creating a new ASP.NET Core Web API, so if you're creating a web API using the .NET Core CLI, you would disable it using the
dotnet new webapi -n TestAPI --no-openapi
Generates OpenAPI Specification Document and Swagger UI
When you enable OpenAPI support in your ASP.NET Core Web API, the project template is including Swashbuckle.AspNetCore as a package and adding code in the
Startup.cs file to generate an OpenAPI Specification Document and adding Swagger and Swagger UI to the middleware pipeline to provide a UI that allows you to explore and test the web API. You can read more about that in my previous tutorial: OpenAPI and Swagger UI in ASP.NET Core 5 Web API.
Publishing the ASP.NET Core Web API in Visual Studio 2019
When publishing the ASP.NET Core Web API there is now an additional option to publish the API to Azure API Management Services. I've removed my personal data from the screenshot, but once you pick the Azure API Management Service, you have the option of creating a new API or connecting to an existing API. You also have the option of skipping the step.
If you don't have the ASP.NET Core Web API configured to create an OpenAPI Specification Document, the publish feature will detect that and ignore publishing the API to Azure API Management Services.
The Sample Weather Forecast ASP.NET Core Web API
This works out-of-the-box using the sample Weather Forecast ASP.NET Core Web API that is included as part of the project template. When you publish the ASP.NET Core Web API with OpenAPI support to an Azure App Services and have the API added to Azure API Management Services, the WeatherForecast - GET method will be added to your API and pointing to your Web API application on Azure App Services. You can test the method from the Azure Portal to verify it works perfectly.
Known Bug When Generating Swagger File for ASP.NET Core Web API
There is a known bug when generating the OpenAPI Specification Document (Swagger file) when your Windows account name has a space in it. This has been a known bug for years and still persists to this day. This is an issue with the swashbuckle.aspnetcore.cli tool that is used to generate the swagger file. This is why it's never a good idea to include a space in your Windows account name... ever. During the publishing process, you will notice the use of the swashbuckle.aspnetcore.cli tool to generate the Swagger file.
Generating swagger file to '...\bin\Release\net5.0\swagger.json'.
If you're using the Azure API Management Service, the new API Management option as part of publishing an ASP.NET Core Web API is quite handy, which is why creating a new ASP.NET Core Web API includes optional support for OpenAPI.
If you're a Microsoft developer interested in more details on what exactly gets configured when including OpenAPI support, check out my previous tutorial: OpenAPI and Swagger UI in ASP.NET Core 5 Web API.
Note that this Azure API Management option as part of the publishing flow is currently only available in Visual Studio 2019 previews. I happen to be be using Visual Studio 2019 16.9 Preview 1, which is the latest preview at this time.
You may also be interested in the fact that the new C# 9 record type is supported in model binding in ASP.NET Core 5 Web API's.