# NSwag: generating OpenAPI specs and typed clients from ASP.NET Core

> NSwag bundles OpenAPI generation and client code generation into one C# toolchain, so you do not run Swashbuckle and AutoRest side by side. Here is how the pieces fit, how to install it, and where it stops being the right tool.

**RicoSuter/NSwag** — The Swagger/OpenAPI toolchain for .NET, ASP.NET Core and TypeScript. 

- Repository: https://github.com/RicoSuter/NSwag
- Website: http://NSwag.org
- Stars: 7,365 · Forks: 1,360
- Language: C#
- License: MIT
- Published: 2026-09-22 · Updated: 2026-09-22 · Language: en
- Canonical page: https://hysenlabs.com/projects/ricosuter-nswag

## The problem NSwag solves for ASP.NET Core teams

A REST API written in C# already contains a description of itself: controllers, action methods, parameter types, DTOs. Keeping a separate OpenAPI document in sync with that code is manual work that decays. NSwag's pitch is that the specification is derived from the assembly or from the running middleware, so the document cannot drift far from the implementation. The README states the project combines the functionality of Swashbuckle (OpenAPI generation) and AutoRest (client generation) in one toolchain, and that neither library is needed alongside it.

The second half of the problem is the consumer. Once a spec exists, someone has to write the HTTP calls, the serialization, the retry and error handling on the client side. NSwag generates C# clients, C# controllers for contract first work, and TypeScript clients. The TypeScript templates listed in the README include JQuery with callbacks, JQuery with promises, AngularJS using $http, Angular (v2+) using the http service, and a Fetch template built on window.fetch and ES6 promises.

Who it is for: teams whose server side is ASP.NET or ASP.NET Core, who want the generated spec served through middleware or emitted at build time, and who want the client for a JavaScript or TypeScript front end generated from the same source of truth. If your API is not .NET, most of the value disappears, because the generators that matter here read C# assemblies and controllers.

## How the toolchain is put together

There are two directions of data flow, and the repository is organised around them. In the first, OpenAPI generators read your code: AspNetCoreOpenApiDocumentGenerator and WebApiOpenApiDocumentGenerator produce a specification from controllers, WebApiToOpenApiCommand does the same for controllers in an external Web API assembly, and TypesToOpenApiCommand emits a document containing only types from .NET assemblies. The README notes that loading .NET Core assemblies is supported.

In the second direction, code generators read a specification and write code: CSharpClientGenerator for C# clients, CSharpControllerGenerator for Web API controllers (the contract first path), and TypeScriptClientGenerator for the front end templates. The generated C# clients can target full .NET, .NET Core, Xamarin and .NET Standard 1.4 in general, and the generator can produce either POCOs or classes implementing INotifyPropertyChanged.

JSON Schema handling and the C#/TypeScript class and interface generation are delegated to NJsonSchema, which the README describes as heavily used by the project. That dependency is the reason NSwag claims better support for things the OpenAPI specification and JSON Schema describe poorly, with inheritance, enums and reference handling called out by name in the README. The practical consequence is that the fidelity of your generated types depends on NJsonSchema's model of your C# types, not only on NSwag's own code.

## Getting the toolchain and generating a first client

The README points at four entry points: the NSwagStudio Windows GUI, the ASP.NET Core and OWIN middlewares, the command line (distributed as a NuGet tool or build target, or through the npm package nswag), and the NuGet packages used directly from C# code. For a first run outside Visual Studio, the npm package is the shortest path, since it works on Windows, macOS and Linux.

The README gives the npm package name as nswag, so the install is a global npm install under that name. The README also documents installation as a NuGet tool or build target, which is the route to take when the CLI has to run inside a build agent that already restores .NET tools.

Generation is driven by a JSON configuration file, or by NSwagStudio if you prefer a GUI. The README describes the CLI as configured via a JSON file, and the generator and template names below are the ones it lists: TypeScriptClientGenerator for the code generator, and Fetch as one of the available TypeScript templates. The configuration points the generator at the served specification and at an output file.

The output file is written to the path in the output key. If you are generating a C# client instead, the same structure applies with CSharpClientGenerator in place of TypeScriptClient, and the README lists CSharpClientGenerator as producing C# clients from an OpenAPI specification. For the server side, the recommended approach in the README is the ASP.NET Core middleware, which serves the spec and can also serve Swagger UI or ReDoc; the tutorial linked from the README is titled Add NSwag to your ASP.NET Core app.

## Where the design creates friction

The configuration file is the centre of gravity, and it is also the main source of confusion. A single configuration can carry a document generator and several code generators, each with its own input and output. When a generation fails, the message usually points at a problem in that file rather than at your controller, which is a poor starting point for debugging. The README does not document rollback or how to recover a partially written output file, so treat generated files as build artifacts and keep them out of manual editing.

Version alignment is the second constraint. The release notes pair each NSwag release with an NJsonSchema release, for example v14.7.1 with NJsonSchema v11.6.1, and v14.7.0 with NJsonSchema v11.6.0. If you install the CLI from npm and the MSBuild targets from NuGet, those are two independent version pins, and nothing in the README states that mismatched versions are safe. The CLI and the build target should be pinned to the same release.

Maintenance is the third point, and it is a fact rather than a judgement. The repository is not archived, but the last push to master was on 2026-09-07 and the most recent release, v14.7.1, was published on 2026-04-20, with v14.6.3 before it on 2025-11-20. Release cadence has slowed compared with the two releases in April 2026. That is not abandonment, but it does mean you should not expect a fix for a newly discovered generator bug to arrive quickly, and it should factor into a decision to make NSwag the single source of client code for a large front end.

## NSwag compared with Swashbuckle and AutoRest

The README positions NSwag against two tools it replaces. Swashbuckle generates OpenAPI documents from ASP.NET Core but does not generate clients. AutoRest generates clients from OpenAPI documents but does not know about your C# controllers. NSwag does both, and the README argues that combining them avoids incompatibilities and gives better support for inheritance, enums and reference handling.

The real difference is where the specification comes from. With Swashbuckle plus a separate client generator, the spec is an artifact you can hand to another team, and the client generator is indifferent to how it was produced. With NSwag, the generator can read the assembly directly through WebApiToOpenApiCommand, which is convenient when the API is C# and awkward when it is not. If your API is written in Go, Java or Python, the C#-aware half of NSwag is dead weight, and a spec-first generator is the better fit.

For TypeScript output specifically, the choice is between NSwag's templates and a generator that consumes an OpenAPI file without any .NET dependency. NSwag's advantage is that the same configuration file can regenerate both the spec and the client in one command. Its disadvantage is that the TypeScript templates are maintained inside a C# project, so a front end team that wants to change the generated output has to work through the template system rather than editing a small JavaScript generator.

## Licence and upgrade cost

NSwag is MIT licensed according to the repository, which permits commercial use and modification. The README lists backers and sponsors on Open Collective, so funding is part of the project's model, but the licence identifier itself does not change with sponsorship. This is not legal advice; if your organisation has policies about generated code provenance, the MIT terms are the relevant text.

The upgrade cost is mostly mechanical but not free. Because each release pairs an NSwag version with an NJsonSchema version, upgrading NSwag means accepting a new schema library as well, and the generated output can shift when NJsonSchema changes how it models a type. Plan for a diff of the generated client after every upgrade, and check the CHANGELOG.md in the repository rather than assuming generated files are stable across minor versions. The most recent release, v14.7.1, was published on 2026-04-20, so the upgrade path is currently a slow one; there is no evidence of a faster channel beyond the preview NuGet packages that the README badges reference.

## When NSwag is the wrong tool

The clearest case is a polyglot backend. If only one service in your system is written in C#, running NSwag for that service and a different generator for the rest means two configuration formats and two sets of generated code conventions in the same repository. A single spec-first generator applied to every service's OpenAPI file is simpler to operate.

A second case is a hand written specification. If you are doing contract first work and the OpenAPI document is authored by hand, NSwag's C#-aware generators add nothing, although CSharpControllerGenerator and the C# and TypeScript client generators remain usable from a document input. The README documents the CSharpControllerGenerator as supporting contract first and schema first development, so the tool is not useless here, only partially applicable.

A third case is a team that needs rapid fixes to generator output. Given the release dates, a bug in the TypeScript template for your framework may sit unfixed for months. If your front end depends on generated code, either fork the templates or budget for hand maintaining the generated client. The README does not document a supported way to override individual template sections outside the NSwagStudio and configuration file mechanisms.

## Conclusion

Adopt NSwag when your API is written in C# and you want the spec and the clients produced by the same toolchain, especially if you need TypeScript output for an Angular or fetch based front end. Do not adopt it if your services are not .NET, if you want a generator that only reads a hand written OpenAPI file and knows nothing about C#, or if you need an actively developed project: the last push to master was on 2026-09-07 and the most recent release, v14.7.1, dates from 2026-04-20. Before committing, verify that your target framework is covered by the current packages, that the client template you need is listed in the README, and that the CLI version you pin matches the NSwag.MSBuild version in your build.

## FAQ

### What is NSwag?

NSwag is a Swagger/OpenAPI 2.0 and 3.0 toolchain for .NET, ASP.NET Core and TypeScript, written in C#. It generates OpenAPI specifications from existing ASP.NET Web API controllers and generates client code from those specifications.

### What is the difference between Swagger and NSwag?

Swagger, or OpenAPI, is the specification format that uses JSON and JSON Schema to describe a RESTful API. NSwag is a toolchain that produces and consumes that format; the README states it combines the functionality of Swashbuckle and AutoRest in one toolchain.

### How do I install NSwag?

The README lists several routes: NSwagStudio for Windows, the ASP.NET Core and OWIN middlewares, the command line distributed as a NuGet tool or build target, the npm package nswag, and the NuGet packages used directly from C# code.

### How do I use a client generated by NSwag in C#?

CSharpClientGenerator produces C# clients from an OpenAPI specification, either as POCOs or as classes implementing INotifyPropertyChanged. The README states the generated clients can be used with full .NET, .NET Core, Xamarin and .NET Standard 1.4 in general.

### How do I use NSwag from MSBuild?

The README lists MSBuild targets as one of the ways to use the toolchain and links to the NSwag.MSBuild wiki page. It also mentions ServiceProjectReference tags in the .csproj file, marked as preview.

### How do I use NSwagStudio?

NSwagStudio is the Windows GUI listed in the README as one of the ways to use the toolchain. The README links to a wiki page for it, and it is an alternative to configuring generation through the command line and a JSON file.

## Sources

- [License: MIT](https://github.com/RicoSuter/NSwag/blob/master/LICENSE)
- [Project website](http://NSwag.org)
- [README](https://github.com/RicoSuter/NSwag/blob/master/README.md)
- [Releases](https://github.com/RicoSuter/NSwag/releases)
- [RicoSuter/NSwag on GitHub](https://github.com/RicoSuter/NSwag)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/ricosuter-nswag