NSwag

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

NSwag is a .NET library and toolset for generating OpenAPI documents and generating clients from API descriptions.

NSwag is a .NET toolset for working with OpenAPI descriptions. It can generate an OpenAPI document for an ASP.NET Core API or turn an existing document into a strongly typed C# client. The client handles API paths, parameters, and request and response serialization, so another C# application needs less hand-written HTTP code. section 11.4 section 11.7

Figure 11.6 Visual Studio or a .NET tool downloads the OpenAPI description locally and installs the code-generation tool from NuGet. When your project builds, the generation tool reads the OpenAPI description and generates a C# class for interacting with the API.

Follow the path from a downloaded OpenAPI JSON file to a generated C# client. The generator runs during a build when the local description file changes. section 11.4

To generate a client with the .NET OpenAPI tool:

• Run an API that exposes an OpenAPI JSON document, and have a C# project ready to call it. section 11.4.2
• Install the tool with `dotnet tool install -g Microsoft.dotnet-openapi`, then use `dotnet openapi add url` to download the document into the client project. section 11.4.2
• Add the required client-generation packages. Check the resulting `<OpenApiReference>` in the project file; it can specify the document, client class name, and namespace. section 11.4.2

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.

The project-file example puts generator options inside `<OpenApiReference>`: use System.Text.Json, generate a client interface, and take the API base address from HttpClient rather than a constructor argument. section 11.4.4

The generated client is partial, so a separate partial class can add methods or implement request hooks without editing generated code. An optional generated interface makes it easier to substitute a fake client in tests. Client generation is not required: Postman or another HTTP client can also call the API. If a newer OpenAPI feature is missing from an upstream document, NSwag cannot generate a client for that missing detail. section 11.4.4 section 11.4 section 11.6.3

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

How deep it goes

Walks through client setup, build integration, and generator options without explaining NSwag's code-generation internals.

Examples

Uses an OpenAPI reference in a .NET project and a client that creates and fetches API data.

What it assumes

Assumes a C# project and a reachable API exposing OpenAPI JSON; supplies the .NET tool setup steps.

What you can do after

Apply it via NSwag and the .NET OpenAPI tool to generate and customize a C# API client.

How it connects

Connects OpenAPI, ASP.NET Core, Swagger UI, Swashbuckle, HttpClient, and dependency injection to API documentation and generated clients.

liveBookmanning.com

Read ASP.NET Core in Action, 3e on liveBook Get the book at manning.com

Related concepts

• Swashbucklealternative to · Swashbuckle is a .NET library that generates and serves OpenAPI documentation, including Swagger UI, for ASP.NET Core applications.
• generated clientproduces · A generated client is source code automatically produced from an API specification to provide a programmatic interface for calling the API's operations.
• OpenAPI specificationuses · The OpenAPI Specification is a standard, machine-readable format for describing HTTP APIs, including their operations, inputs, outputs, data structures, and security requirements.
• OpenAPI Generatoralternative to · OpenAPI Generator is a code-generation tool that creates client libraries, server stubs, and related artifacts from OpenAPI documents.
• System.Text.Jsonalternative to · System.Text.Json is a .NET library providing APIs for serializing, deserializing, reading, writing, and processing JSON data.

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.