liveBook · Manning

Generated client

As explained in ASP.NET Core in Action, 3e

Client code generation is the automatic production of source code for calling an API from an API description.

A generated client is C# code produced from an API’s OpenAPI description. Instead of writing HTTP calls by hand, you call methods on a generated class. NSwag supplies the endpoint paths, substitutes path parameters, serializes requests, deserializes responses, and checks error status codes. section 11.4.3

To create one for an ASP.NET Core API:

  • Run the API and make its OpenAPI JSON document accessible. In a C# client project, use Visual Studio’s Add > Service Reference > OpenAPI workflow, or install Microsoft.dotnet-openapi and run dotnet openapi add url with the document URL. section 11.4.1 section 11.4.2
  • Check the resulting <OpenApiReference> in the project file. It identifies the downloaded description and can specify the generated class name and namespace. NSwag.ApiDescription.Client performs code generation; check the added NuGet packages for updates if the project does not build. section 11.4.1 section 11.4.2
  • Build the project. The generated C# file is typically in obj; you can also navigate to the class with Go To Definition. section 11.4.3

Calling a fruit API

Create a FruitClient with the API base address and an HttpClient. Calling FruitPOSTAsync("123", new Fruit { Name = "Banana", Stock = 100 }) sends a create request; FruitGETAsync("123") fetches it. Those method names work, but they are awkward: adding WithName() to each API endpoint supplies an OpenAPI operation ID that NSwag can use for better names. section 11.4.3

Generation options belong in the project’s <OpenApiReference>. You can switch from the default Newtonsoft.Json serialization to System.Text.Json, generate an interface for substituting a fake client in tests, or use HttpClient.BaseAddress instead of a string constructor argument. The generated class is partial, so you can add your own methods in another file; partial-method hooks are available around requests. section 11.4.4

Listing 11.7 Customizing NSwag generator options
<OpenApiReference Include="OpenAPIs\fruit.json"
  SourceUrl="http://localhost:5062/swagger/v1/swagger.json"
  Namespace="Fruit"
  ClassName="FruitClient" >
<Options>/UseBaseUrl:false /GenerateClientInterfaces:true 
  ➥ /JsonLibrary:SystemTextJson</Options>    #1
</OpenApiReference>                           #2
#1 Customizes the options NSwag uses for code generation
#2 Make sure to close the outer XML element to keep the XML valid.

Shows the <Options> switches for System.Text.Json, a generated interface, and an HttpClient-based address. section 11.4.4

When the API description changes, refresh the saved OpenAPI document in Visual Studio or run dotnet openapi refresh with its URL. Then rebuild: NSwag regenerates the client from the updated description. Without that refresh, changes such as improved operation IDs will not appear in the generated code. section 11.4.5

How ASP.NET Core in Action, 3e covers it

How deep it goes
Walks through generation, calls, customization, and refresh, while treating NSwag’s generated implementation as tooling rather than building a generator.
Examples
Uses a fruit API client that creates and fetches a fruit, plus project-file options for generation.
What it assumes
Requires a C# client project and an accessible OpenAPI JSON document from a running API.
What you can do after
Apply it via NSwag to generate, use, customize, and refresh a C# client from an OpenAPI document.
How it connects
Connects OpenAPI operation IDs and endpoint metadata to NSwag method names, and HttpClient and JSON serialization to runtime calls.
Cover of ASP.NET Core in Action, 3e
liveBookmanning.com
Read ASP.NET Core in Action, 3e on liveBook Get the book at manning.com

Related concepts

This explainer was generated by Manning's knowledge graph from the text of ASP.NET Core in Action, 3e. The section links point to the parts of the book it draws on.