# NSwag

> NSwag is the Swagger/OpenAPI toolchain for .NET, ASP.NET Core and TypeScript, written in C# and maintained by Rico Suter under MIT. It generates Swagger 2.0 and OpenAPI 3.0 documents from ASP.NET (Core) controllers and .NET types, and generates C# clients, C# Web API controllers and TypeScript clients back out of those documents — combining what Swashbuckle and AutoRest do separately into one toolchain. NSwag operates no hosted API of its own: it is consumed as NuGet packages, an npm-distributed CLI, MSBuild targets, and NSwagStudio, a Windows GUI. Current release 14.7.1 (2026-04-20).

Generated by the API Evangelist enrichment pipeline on 2026-08-06 from the project's own GitHub repository, wiki, releases and package registries. This file is not published by NSwag.

Important: NSwag.org, still declared as the project homepage on GitHub and in every NuGet package, no longer resolves to the project (HTTPS times out, HTTP returns 403). The live documentation is the GitHub wiki.

## Project

- [Repository](https://github.com/RicoSuter/NSwag): Source, issues and releases. MIT.
- [Wiki](https://github.com/RicoSuter/NSwag/wiki): The live documentation.
- [Getting Started](https://github.com/RicoSuter/NSwag/wiki/Getting-Started)
- [Roadmap](https://github.com/RicoSuter/NSwag/wiki/Roadmap): Majors tracked as GitHub issues; v14 = issue #2181.
- [Releases](https://github.com/RicoSuter/NSwag/releases): The real change log — CHANGELOG.md in the repo stops at v11.3.
- [Contributing](https://github.com/RicoSuter/NSwag/blob/master/CONTRIBUTING.md)
- [License (MIT)](https://github.com/RicoSuter/NSwag/blob/master/LICENSE.md)

## What it does

- [OpenAPI generation from ASP.NET Core](https://github.com/RicoSuter/NSwag/wiki/AspNetCoreOpenApiDocumentGenerator): Reads the ApiExplorer to emit a document.
- [OpenAPI generation from ASP.NET Web API](https://github.com/RicoSuter/NSwag/wiki/WebApiOpenApiDocumentGenerator): For classic Web API assemblies; not for ASP.NET Core.
- [OpenAPI from .NET types](https://github.com/RicoSuter/NSwag/wiki/TypesToOpenApiCommand): Emit a document describing only named types.
- [C# client generator](https://github.com/RicoSuter/NSwag/wiki/CSharpClientGenerator)
- [C# controller generator](https://github.com/RicoSuter/NSwag/wiki/CSharpControllerGenerator): Contract-first / schema-first.
- [TypeScript client generator](https://github.com/RicoSuter/NSwag/wiki/TypeScriptClientGenerator): Fetch, Angular, AngularJS, Aurelia, Axios (preview), jQuery templates.
- [ASP.NET Core middleware](https://github.com/RicoSuter/NSwag/wiki/AspNetCore-Middleware): Serve the document plus Swagger UI and ReDoc.
- [OpenAPI 3 support notes](https://github.com/RicoSuter/NSwag/wiki/OpenAPI-3-support): The internal model is Swagger 2.0-shaped with OpenAPI 3.0 mapped onto it; full 3.0 serialization is documented as incomplete. No OpenAPI 3.1 support is claimed.
- [YAML support](https://github.com/RicoSuter/NSwag/wiki/YAML-support): via NSwag.Core.Yaml.

## How it is used

- [Command line](https://github.com/RicoSuter/NSwag/wiki/CommandLine): run, new, aspnetcore2openapi, webapi2openapi, types2openapi, openapi2csclient, openapi2cscontroller, openapi2tsclient, jsonschema2csclient, jsonschema2tsclient.
- [Configuration document](https://github.com/RicoSuter/NSwag/wiki/NSwag-Configuration-Document): nswag.json describes one input generator and many code-generator outputs; `nswag run` executes it. The recommended entry point.
- [MSBuild integration](https://github.com/RicoSuter/NSwag/wiki/NSwag.MSBuild)
- [NSwagStudio](https://github.com/RicoSuter/NSwag/wiki/NSwagStudio): Windows GUI that authors and runs the same nswag.json.
- [npm package](https://www.npmjs.com/package/nswag): `npm install nswag -g`
- [.NET global tool](https://www.nuget.org/packages/NSwag.ConsoleCore): `dotnet tool install --global NSwag.ConsoleCore`
- [Chocolatey](https://community.chocolatey.org/packages/nswagstudio): `choco install nswagstudio`

## Packages

- [All NSwag packages on NuGet](https://www.nuget.org/packages?q=NSwag): One version line across NuGet, npm and Chocolatey.
- [NSwag.Core](https://www.nuget.org/packages/NSwag.Core): The OpenAPI reader/writer model.
- [NSwag.AspNetCore](https://www.nuget.org/packages/NSwag.AspNetCore): Middleware plus Swagger UI and ReDoc.
- [NSwag.MSBuild](https://www.nuget.org/packages/NSwag.MSBuild)
- [NSwag.ApiDescription.Client](https://www.nuget.org/packages/NSwag.ApiDescription.Client): Visual Studio OpenAPI references.
- [NJsonSchema](https://github.com/RicoSuter/NJsonSchema): The pinned dependency that drives JSON Schema handling and generated types; every NSwag release names its version.

## Support

- [Issues](https://github.com/RicoSuter/NSwag/issues)
- [Discord](https://discord.gg/BxQNy25WF6)
- [Stack Overflow](https://stackoverflow.com/questions/tagged/nswag)
- [Sponsor via GitHub](https://github.com/sponsors/RicoSuter)
- [Open Collective](https://opencollective.com/nswag)

## API Evangelist artifacts

- [apis.yml](https://raw.githubusercontent.com/api-evangelist/nswag/refs/heads/main/apis.yml)
- [Packages](https://raw.githubusercontent.com/api-evangelist/nswag/refs/heads/main/packages/nswag-packages.yml)
- [CLI](https://raw.githubusercontent.com/api-evangelist/nswag/refs/heads/main/cli/nswag-cli.yml)
- [Changelog](https://raw.githubusercontent.com/api-evangelist/nswag/refs/heads/main/changelog/nswag-changelog.yml)
- [Lifecycle](https://raw.githubusercontent.com/api-evangelist/nswag/refs/heads/main/lifecycle/nswag-lifecycle.yml)
- [Conformance](https://raw.githubusercontent.com/api-evangelist/nswag/refs/heads/main/conformance/nswag-conformance.yml)
- [Domain security](https://raw.githubusercontent.com/api-evangelist/nswag/refs/heads/main/security/nswag-domain-security.yml)
- [Well-known probe](https://raw.githubusercontent.com/api-evangelist/nswag/refs/heads/main/well-known/nswag-well-known.yml)

## Gaps

- No SECURITY.md and no /.well-known/security.txt — there is no published way to report a vulnerability in a toolchain with 201M+ downloads on NSwag.Core alone.
- No first-party JSON Schema for nswag.json; the only one in circulation is a stale draft-04 copy on SchemaStore using pre-v12 property names.
- No OpenAPI 3.1 support.
- v14.7.0 is retracted in prose in its release notes but remains installable from NuGet, so version-range resolution will not surface the warning.