NSwag is an MIT-licensed Swagger/OpenAPI 2.0 and 3.0 toolchain written in C# for .NET, ASP.NET Core, and TypeScript developers who need to generate OpenAPI specifications from ASP.NET Web API controllers and generate C# or TypeScript clients from those specifications.

What it is

NSwag is a Swagger/OpenAPI 2.0 and 3.0 toolchain for .NET, .NET Core, Web API, ASP.NET Core, TypeScript, and other platforms, written in C#. It provides tools to generate OpenAPI specifications from existing ASP.NET Web API controllers and to generate client code from those specifications. The project uses NJsonSchema for .NET for JSON Schema handling and C#/TypeScript class and interface generation. The OpenAPI/Swagger specification uses JSON and JSON Schema to describe a RESTful web API, and NSwag turns that description into code and documentation artifacts.

The concrete problem NSwag solves is the gap between server-side API definitions and client-side consumption. Instead of using one library for OpenAPI/Swagger generation and another for client generation, NSwag combines the functionality of Swashbuckle (OpenAPI/Swagger generation) and AutoRest (client generation) in one toolchain; those two libraries are not needed when using NSwag. This avoids many incompatibilities and supports features that the OpenAPI specification or JSON Schema do not describe well, such as inheritance, enum handling, and reference handling. The result is a single path from ASP.NET Web API controllers to OpenAPI specs, served documentation, and generated clients.

Key capabilities

• Generate Swagger 2.0 and OpenAPI 3.0 specifications from C# ASP.NET (Core) controllers.
• Serve specifications through ASP.NET (Core) or OWIN middleware, optionally with Swagger UI or ReDoc.
• Generate C# or TypeScript clients and proxies from those specifications.
• Automate the toolchain through a CLI distributed as a NuGet tool or build target, or through the npm package nswag.
• Configure the CLI with a JSON file or use the NSwagStudio Windows UI.
• Use NSwag in C# code through NuGet packages or in builds through MSBuild targets.
• Use ServiceProjectReference tags in a .csproj file (preview) and integrate with Azure V2 Functions through the external NSwag.AzureFunctionsV2 project.

Who uses it and how

• .NET and ASP.NET Core teams that expose REST APIs through ASP.NET Web API controllers and want OpenAPI specs generated from those controllers instead of written by hand.
• Teams that need generated TypeScript clients for jQuery, AngularJS, Angular 2+, Aurelia, KnockoutJS, and similar front-end stacks.
• Windows developers who prefer the NSwagStudio GUI, and command-line users on Windows, Mac, and Linux through Mono, a .NET Core console binary, or the npm package nswag.
• Applications that serve their own OpenAPI specification and documentation from ASP.NET Core or OWIN middleware, with Swagger UI or ReDoc as the rendered UI.
• Build pipelines that use NuGet tooling, MSBuild targets, or ServiceProjectReference tags in .csproj, and Azure Functions V2 projects that use the external NSwag.AzureFunctionsV2 package.

Getting started

Install the NuGet tool or build target, or the npm package nswag, and configure the CLI with a JSON file or the NSwagStudio Windows UI. For ASP.NET Core applications, add the OpenAPI or OpenAPI UI middleware and optionally serve Swagger UI or ReDoc directly from the application.

How it compares

No list of paid products this project replaces is provided in the facts. Within the .NET OpenAPI space, NSwag combines the functionality of Swashbuckle for OpenAPI/Swagger generation and AutoRest for client generation in one toolchain, so those two libraries are not needed when using NSwag. It relies on NJsonSchema for JSON Schema handling and C#/TypeScript class and interface generation, which supports inheritance, enum, and reference handling beyond what the OpenAPI specification or JSON Schema alone describes well.

When to use it — and when not to

Choose NSwag when the API is built with ASP.NET Web API or ASP.NET Core and the team wants one toolchain for specification generation, documentation middleware, and C# or TypeScript client generation. Teams outside the .NET stack, or teams that do not want to run ASP.NET Core or OWIN middleware to serve Swagger UI or ReDoc, may find the toolchain less direct. The repository has 2,057 open issues, ServiceProjectReference support is marked preview, and Azure Functions V2 support lives in an external project, so users should expect some rough edges and community-dependent support.