In this article, we'll look at usingOpenAPI with.NET Core. OpenAPI is a specification for describing RESTful APIs. First, I'll show you how to use OpenAPI to describe the APIs provided by an ASP.NET Core service. Then, we'll use the API description to generate a strongly-typed client to use the web service with C#.

Writing OpenAPI descriptions

Developers use theOpenAPI specification to describe RESTful APIs. We can then use OpenAPI descriptions to generate a strongly-typed client library that is capable of accessing the APIs.

Note:Swagger is sometimes used synonymously with OpenAPI. It refers to a widely used toolset for working with the OpenAPI specification.

Build the web service

In this section, we'll use theopen sourceSwashbuckle.AspNetCore package to provide an OpenAPI description of an ASP.NET Core application.

We start by creating awebapi template application:

$ dotnet new webapi -o WebApi1$ cd WebApi1

Thewebapi template includes a REST API to get a weather forecast. The API is implemented in theWeatherForecastController.cs file.

Next, we add theSwashbuckle.AspNetCore package:

$ dotnet add package Swashbuckle.AspNetCore

Now, we make a few edits to theStartup.cs file:

public void ConfigureServices(IServiceCollection services)  {    services.AddControllers();++   services.AddSwaggerGen();  }  public void Configure(IApplicationBuilder app, IWebHostEnvironment env)  {    ....    app.UseHttpsRedirection();+   app.UseSwagger();++   app.UseSwaggerUI(c =>+   {+     c.SwaggerEndpoint("/swagger/v1/swagger.json", "My API V1");+   });+    app.UseRouting();    app.UseAuthorization();

In theConfigureServices method, we callAddSwaggerGen. CallingAddSwaggerGen makes the API description available. The API can then be consumed through ASP.NET Core's dependency injection (DI) system.UseSwagger uses these descriptions to create an HTTP endpoint at/swagger/v1/swagger.json. TheUseSwaggerUI then provides a user interface (UI) at/swagger that allows users to easily consume the exposed API from a browser.

Note: The methods called inStartup.cs accept a delegate for configuration. For useful options, see the ASP.NET Core documentation,Get started with Swashbuckle and ASP.NET Core.

Run the app

You can run the application and browse to the Swagger UI, which is shown in Figure 1.

TheSwashbuckle.AspNetCore packages picked up the ASP.NET endpoints. The exposed UI makes it easy to invoke the REST endpoints.

Consuming OpenAPI descriptions

In this section, we'll look at consuming a RESTful API that has an OpenAPI description. To consume the API, we'll use the open source package,NSwag.ApiDescription.Client.

First, we create a newconsole project, and download the OpenAPI description from our ASP.NET application:

$ dotnet new console -o console$ cd console$ mkdir openapi$ wget --no-check-certificate https://localhost:5001/swagger/v1/swagger.json -O openapi/weather.json

Now, we'll make a few edits to the project file. These edits will be used to generate a strongly-typed client when the .NET project is built:

<Project Sdk="Microsoft.NET.Sdk">   <PropertyGroup>     <OutputType>Exe</OutputType>     <TargetFramework>netcoreapp3.1</TargetFramework>   </PropertyGroup>+  <ItemGroup>+    <PackageReference Include="Newtonsoft.Json" Version="12.0.2" />+    <PackageReference Include="NSwag.ApiDescription.Client" Version="13.0.5" />+  </ItemGroup>+  <ItemGroup>+    <OpenApiReference Include="openapi/weather.json" Namespace="WeatherService">+      <ClassName>WeatherClient</ClassName>+      <OutputPath>WeatherClient.cs</OutputPath>+    </OpenApiReference>+  </ItemGroup> </Project>

We've added references to theNSwag.ApiDescription.Client andNewtonsoft.Json packages. AnOpenApiReference element refers to the API description that we downloaded earlier. It adds attributes that are required to generate the code, such as the class name, namespace, and filename.

Build the client

Now, we'll invoke thebuild command. Invoking the command generates aWeatherClient.cs file, which lives under theobj directory:

$ dotnet build

We can now edit theProgram.cs file and use the strongly-typedWeatherClient class that we've just generated:

static async Task Main(string[] args){  // Configure HttpClientHandler to ignore certificate validation errors.  using var httpClientHandler = new HttpClientHandler();  httpClientHandler.ServerCertificateCustomValidationCallback = (message, cert, chain, errors) => { return true; };  // Create WeatherClient.  using var httpClient = new HttpClient(httpClientHandler);  var weatherClient = new WeatherService.WeatherClient("http://localhost:5000", httpClient);  // Call WeatherForecast API.  var forecast = await weatherClient.WeatherForecastAsync();  foreach (var item in forecast)  {    Console.WriteLine($"{item.Date} - {item.Summary}");  }}

Run the app

Finally, we run the application:

$ dotnet run7/1/2020 1:18:18 PM +02:00 - Mild7/2/2020 1:18:18 PM +02:00 - Bracing7/3/2020 1:18:18 PM +02:00 - Freezing7/4/2020 1:18:18 PM +02:00 - Balmy7/5/2020 1:18:18 PM +02:00 - Bracing

As you can see, the weather report is mixed.

Conclusion

In this article, you learned about the OpenAPI specification, which is sometimes used synonymously with Swagger. Developers use the OpenAPI spec to describe RESTful APIs in preparation for being consumed by a client. I showed you how to use theSwashbuckle.AspNetCore package to provide an OpenAPI description of an API implemented using ASP.NET Core. Then, we used theNSwag.ApiDescription.Client package to generate a strongly-typed client capable of consuming the API.