[opensourcedex]

NSwag is a free, open source api development & testing project written in C# and released under MIT. It has 7,369 GitHub stars, 1,363 forks and 2,057 open issues, and was last pushed 2 months ago. On this registry it ranks #32 of 187 tracked projects in API Development & Testing, with 5 head-to-head comparisons available. It gained 4 stars over the last 30 tracked days.

What is NSwag?

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.

project readme (upstream, from github) — read inline

NSwag: The Swagger/OpenAPI toolchain for .NET, ASP.NET Core and TypeScript

NSwag | NJsonSchema | Apimundo | Namotion.Reflection

NuGet Version npm NuGet Version Preview build Discord StackOverflow Wiki Backers on Open Collective Sponsors on Open Collective

:point_right: Announcing Apimundo: An API documentation system based on NSwag and NJsonSchema :point_left:

NSwag is a Swagger/OpenAPI 2.0 and 3.0 toolchain for .NET, .NET Core, Web API, ASP.NET Core, TypeScript (jQuery, AngularJS, Angular 2+, Aurelia, KnockoutJS and more) and other platforms, written in C#. The OpenAPI/Swagger specification uses JSON and JSON Schema to describe a RESTful web API. The NSwag project provides tools to generate OpenAPI specifications from existing ASP.NET Web API controllers and client code from these OpenAPI specifications.

The project combines the functionality of Swashbuckle (OpenAPI/Swagger generation) and AutoRest (client generation) in one toolchain (these two libs are not needed). This way a lot of incompatibilites can be avoided and features which are not well described by the OpenAPI specification or JSON Schema are better supported (e.g. inheritance, enum and reference handling). The NSwag project heavily uses NJsonSchema for .NET for JSON Schema handling and C#/TypeScript class/interface generation.

ToolchainDiagram

The project is developed and maintained by Rico Suter and other contributors.

Features

Ways to use the toolchain

Tutorials

OpenAPI/Swagger Generators

Code Generators

  • CSharp Client
    • CSharpClientGenerator
      • Generates C# clients from an OpenAPI specification
      • Generates POCOs or classes implementing INotifyPropertyChanged supporting DTOs
      • The generated clients can be used with full .NET, .NET Core, Xamarin and .NET Standard 1.4 in general
  • CSharp Controllers (contract first/schema first development)
    • CSharpControllerGenerator
      • Generates Web API Controllers based on an OpenAPI specification (ASP.NET Web API and ASP.NET Core)
  • TypeScript Client
    • TypeScriptClientGenerator
      • Generates TypeScript clients from an OpenAPI specification
      • Available templates/supported libraries:
        • JQuery with Callbacks, JQueryCallbacks
        • JQuery with promises JQueryPromises
        • AngularJS using $http, AngularJS
        • Angular (v2+) using the http service, Angular
        • window.fetch API and ES6 promises, Fetch (use this template in your React/Redux app)
        • Aurelia using the HttpClient from aurelia-fetch-client, Aurelia (based on the Fetch template)
        • Axios (preview)

Downloads

NPM Packages

  • NSwag: Command line tools (.NET and .NET Core) distributed as NPM package

NuGet Packages

Specification
  • NSwag.Core
    • The OpenAPI/Swagger reader and writer classes, see OpenApiDocument (.NET Standard 1.0 / 2.0 and .NET 4.5)
  • NSwag.Core.Yaml (.NET Standard 1.3 / 2.0 and .NET 4.5)
    • Extensions to read and write YAML OpenAPI specifications
  • NSwag.Annotations (.NET Standard 1.0 / 2.0 and .NET 4.5)
    • Attributes to decorate Web API controllers to control the OpenAPI generation
OpenAPI generation
Code generation
ASP.NET and ASP.NET Core
Frontends
  • NSwag.AssemblyLoader (.NET Standard 1.6 / 2.0 and .NET 4.5.1):
    • Classes to load assemblies in an isolated AppDomain and generate OpenAPI specs from Web API controllers
  • NSwag.Commands (.NET Standard 1.6 / 2.0 and .NET 4.5.1+):
    • Commands for the command line tool implementations and UI
  • NSwag.MSBuild (MSBuild .targets):
    • Adds a .targets file to your Visual Studio project, so that you can run the NSwag command line tool in an MSBuild target, see MSBuild
  • NSwag.ConsoleCore (.NET Core 1.0, 1.1, 2.0, 2.1 and 2.2):
    • Command line tool for .NET Core (dotnet nswag)
    • ``
  • NSwagStudio (Chocolatey, Windows):
    • Package to install the NSwagStudio and command line tools via Chocolatey
CI NuGet Feed

https://www.myget.org/F/nswag/api/v3/index.json

The NuGet packages may require the Microsoft.NETCore.Portable.Compatibility package on .NET Core/UWP targets (if mscorlib is missing).

LayerDiagram

Usage in C#

To register the middlewares to generate an OpenAPI spec and render the UI, register NSwag in Startup.cs: 

public class Startup
{
    ...

    public void ConfigureServices(IServiceCollection services)
    {
        services.AddOpenApiDocument(); // add OpenAPI v3 document
//      services.AddSwaggerDocument(); // add Swagger v2 document
    }

    public void Configure(IApplicationBuilder app, IHostingEnvironment env, ILoggerFactory loggerFactory)
    {
        ...

        app.UseOpenApi(); // serve OpenAPI/Swagger documents
        app.UseSwaggerUi(); // serve Swagger UI
        app.UseReDoc(); // serve ReDoc UI
    }
}

The following code shows how to read an OpenAPI/Swagger specification and generate C# client classes to call the described web services: 

var document = await OpenApiDocument.FromFileAsync("openapi.json");
var clientSettings = new CSharpClientGeneratorSettings 
{
    ClassName = "MyClass",
    CSharpGeneratorSettings = 
    {
        Namespace = "MyNamespace"
    }
};

var clientGenerator = new CSharpClientGenerator(document, clientSettings);
var code = clientGenerator.GenerateFile();

Check out the project Wiki for more information.

NSwagStudio

The generators can be used in a comfortable and simple Windows GUI called NSwagStudio:

Sponsors, support and consulting

Companies or individuals which paid a substantial amount for implementing, fixing issues, support or sponsoring are listed below. Thank you for supporting this project! You can also become a financial contributor:

Please contact Rico Suter for paid consulting and support.

Contributors

This project exists thanks to all the people who contribute. [Contribute].

Sponsors

Support this project by becoming a sponsor. Your logo will show up here with a link to your website.

Top sponsors:

Sponsors:

Backers

Thank you to all our backers!

Frequently asked questions

Is NSwag free to use?

NSwag is open source under the MIT licence. There is no licence fee and no seat count — you can self-host it or, where the project offers one, pay a vendor for a managed version instead.

What does NSwag do?

The Swagger/OpenAPI toolchain for .NET, ASP.NET Core and TypeScript.

What is NSwag written in?

NSwag is primarily written in C#. Its source is publicly available at https://github.com/RicoSuter/NSwag, and it has 7,369 GitHub stars.