Strongly Typed Client Web API Generators (WebApiClientGen) generate client API code in C# and TypeScript from ASP.NET Core Web API.

WebApiClientGen does not rely on Swagger/OpenAPI definitions. Instead, it walks through the runtime type information of a running Web API in a debug build, avoiding the inherent limitations of OpenAPI when analyzing .NET types and Web API behaviors, ultimately delivering a better developer experience for ASP.NET Core Web API developers, .NET client developer and TypeScript client developers.

Downloads and Use Cases

The component set is released mostly through NuGet.

1. Fonlow.WebApiClientGenCore for generating C# client API. And to generate TypeScript client APIs optimized for some development frameworks or libraries, add the following plugins:

   1. Fetch API
   2. Angular 6+
   3. Angular 6+ with Reactive Forms as explained
   4. AXIOS
   5. Aurelia
   6. jQuery and HttpClient helper library

2. Fonlow.TypeScriptCodeDOMCore for developing TypeScript code generator through the CodeDOM approach.

3. Fonlow.Poco2TSCore for developing TypeScript code generator through the CodeDOM approach for POCO and more.

4. Poco2TSCore.exe, a console app for generating TypeScript type interfaces from POCO.

5. Fonlow.DocCommentCore for reading XML document of an .NET assembly

6. Fonlow.DataOnlyExtensions with JSON converters for handling date only scenarios between the clients and server which sit in different timezones. 3 NuGet packages are available including one for .NET Framework.

Seamless Development of ASP.NET Core Web API and Client Programs

You or your team is developing both Web API backend and client programs.

Setup

1. Import Fonlow.WebApiClientGenCore, and optionally one of the plugins for popular JavaScript libs and frameworks.
2. Add CodeGenController.cs to folder "Controllers"
3. Ensure ApiExplorer visible through having the following in program.cs:

builder.Services.AddControllers(configure =>
{
#if DEBUG
	configure.Conventions.Add(new Fonlow.CodeDom.Web.ApiExplorerVisibilityEnabledConvention());//To make ApiExplorer be visible to WebApiClientGen
#endif
})

4. Define the settings of the CodeGen.

Generate Client API Codes from Web API

1. Launch the debug build of Web API
2. Post the settings of the CodeGen to Web API.

Alternatively, you can use PowerShell scripts to automate. Please refer to these 2 examples:

1. CreateDemoCoreWebClientApi.ps1
2. CreateDemoTextJsonWebClientApi.ps1

Then you will get client codes like:

1. .NET Client API in C#.
2. Client API in TypeScript for Angular Reactive Forms or for Fetch.

Key Features

1. Client API codes generated are directly mapped from the runtime type information of the Web API controller methods, .NET primitive types and POCO classes.
2. Doc comments of controller methods and POCO classes are copied.
3. Some validation attributes are copied to C# client API codes.
4. Some validation attributes are used to generate doc comments for TypeScript codes.
5. Some validation attributes are transformed into validators of Angular Reactive Forms.
6. .NET generic types are supported.

Key Benefits for Developer Experience

1. WebApiClientGen is seamlessly integrated with ASP.NET Core Web API with very little steps/overheads to setup, maintain and synchronize between Web API and client APIs, during RAD or Agile Software Development.
2. Support all .NET primitive types including decimal.
3. Support DataTime, DataTimeOffset, DateOnly, Array, Tuple, Dynamic Object, Dictionary and KeyValuePair
4. Strongly typed generated codes are subject to design time type checking and compile time type checking.
5. Provide high level of abstraction, shielding application developers from repetitive technical details of RESTful practices and traditional codes of AJAX calls.
6. Rich meta info including doc comments make IDE intellisense more helpful, so application developers have less need of reading separated API documents.
7. Generated doc comments based on .NET validation attributes.
8. Generated doc comments based on numeric types, DateOnly and GUID for TypeScript codes.
9. Generated TypeScript codes conform to the TypeScript strict mode, and the generated Angular 2+ codes conform to the Angular strict mode.
10. The format of generated TypeScript codes conform to the default of Visual Studio Code.

Examples

1. POCO classes
2. Web API
3. Generated client API C# codes
4. Client codes using the generated library in C#
5. Generated client data models and API in TypeScript for Angular 2, for Fetch, for Aurelia and for Axios
6. Client codes using the generated library in TypeScript
7. Online Demo with Angular Heroes hosted in GitHub.IO talking to a real backend

Remarks:

1. JavaScript codes compiled from generated TypeScript codes could be used in JS applications, however, obviously no type info will be available, while application programmers may still enjoy intellisense and abstraction from AJAX details.
   1. React and Vue.js applications typically use Axios or Fetch API for HTTP requests. Since June 2019, babel has supported namespaces thanks to this pull request, so you should be able to do React TSX programming with generated TypeScript codes.

Concepts

1. Web API vendors / developers should provide client API libraries to developers of client programs, as Google and Amazon etc. would do in order to make the RESTful or RPC Web API reach wider consumers (internal and external) efficiently.
2. To client developers, classic function prototypes like ReturnType DoSomething(Type1 t1, Type2 t2 ...) is the API function, and the rest is the technical implementation details of transportation: TCP/IP, HTTP, SOAP, resource-oriented, CRUD-based URIs, RESTful, XML and JSON etc. The function prototype and a piece of API document should be good enough for calling the API function.
3. The better you have separation of concerns in your Web API design, the more you will benefit from the components of this project in order to deliver business values sooner, with less handcrafted codes , less repetitive tasks and less chances of human mistakes.

Expected Programming Practices

Strongly Typed Function Prototype

ReturnType DoSomething(Type1 t1, Type2 t2 ...)

		[HttpGet]
		[Route("getPerson/{id}")]
		public Person GetPerson(long id)

Model Validation through Middleware

Rather than writing explicit codes of validating the request payload, it is expected that you use middleware to validate. For example:

public void ConfigureServices(IServiceCollection services)
{
	services.AddControllers(
		options =>
		{
			options.Filters.Add(new ValidateModelAttribute()); // wholesale style to check model binding for all API calls.

References:

• Model Validation in ASP.NET Web API
• Model Validation in ASP.NET Core MVC and Razor Pages

Model Validation through ApiControllerAttribute

For example:

	[ApiController]
	[Route("api/[controller]")]
	public class HeroesController : ControllerBase
	{

Non-2xx HTTP Status Codes Handled by Middleware, optional

Even if you explicitly write codes in an API function to handle exceptions and return non-2xx HTTP status code, you should have a safty net of catching uncaught exceptions and return HTTP status codes.

References:

• ASP.NET Core Middleware

More Documentations

1. WIKI
2. Settings Explained
3. Generate C# .NET Client API for ASP.NET Web API / Local Copy
4. Generate TypeScript Client API for ASP.NET Web API / Local Copy
5. ASP.NET Web API, Angular2, TypeScript and WebApiClientGen / Local Copy
6. Generate C# Client API for ASP.NET Core Web API / Local Copy
7. Intended Solutions for Intentional Limitations of Strongly Typed OpenAPI Client Generators / Local Copy. The article is just using OpenApiClientGen as an example, while the principles and solutions can be applied to generated codes by WebApiClientGen for your client apps.
8. DateOnly in ASP.NET Core 6 / Local Copy

Demo Applications

The Demo applications in this repository are mainly for testing WebApiClientGen during development. And there are other demo applications in the following repositories, demostrating how real world applications could utilize WebApiClientGen:

1. .NET Core Demo for ASP.NET Core MVC, Web API, ASP.NET Core + Angular, MAUI, fetchAPI, vue TS and React TS.
2. WebApiClientGen Examples for .NET Framework, .NET Standard, Xamarin, and vue TS.
3. WebApiClientGen vs Swagger

These demo applications are actively maintained and kept up-to-date with the latest frameworks. If you are still staying with some older frameworks like Angular 4 or 5 or .NET Core 2.0, you may navigate to respective tags of the repositories and checkout.

Tour of Heroes

Tour of Heroes is the official Angular tutorial demo app.

To illustrate the programmer experience of using WebApiClientGen, the following demo apps are crafted with similar architectural design for the same functional features on various development frameworks or libraries, however, talking to a real backend.

1. Angular 2+, and article: Generate Typed FormGroup of Angular Reactive Forms with ASP.NET Core Web API / Local Copy
2. Xamarin
3. MAUI. Migrated from Xamarin Heroes.
4. Aurelia. Integration test suite included.
5. React. Integration test suite included.
6. Article: Tour of Heroes: Blazor WebAssembly Standalone App / Local Copy

NewtonSoft.Json or System.Text.Json

While WebApiClientGen supports both, however, the primary support has shifted to System.Text.Json since 2024.

NewtonSoft.Json still has a few advantages upon certain scenarios and contexts:

1. If you have a lot POCO classes decorated by DataContractAttributes, because of supporting legacy apps, or supporting both XML and JSON serialization, NewtonSoft.Json gives you inherent support, while System.Text.Json provides some troublesome and indirect support since .NET 7.
2. For some array types and dynamic, NewtonSoft.Json is still better.

Package Diagram of Downloads

Hints:

• OpenApiClientGen based on key components of WebApiClientGen is a spin-off for generating client API codes in C# and TypeScript according to a definition file of Swagger/Open API Specification. Therefore the codes generated look fairly similar to what generated by WebApiClientGen.

Remarks:

• The development had started in year 2015 supporting .NET Framework, then .NET Core 2. And Tag "LastCore31" is to mark the last snapshot supporting .NET Framework 4.6.2 and .NET Core 3.1.
• Starting from 2021-02-10, the development will support only .NET 5 and onward.
• Wiki contents about .NET Framework will be kept in foreseeable future.

Contributing

CONTRIBUTING.md