README.md

NSwag: The Swagger API toolchain for .NET and TypeScript

CI:

NSwag is a Swagger 2.0 API toolchain for .NET, TypeScript and other platforms, written in C#. The Swagger specification uses JSON and JSON Schema to describe a RESTful web API. The project provides tools to generate Swagger specifications from existing Web API controllers and client code from these Swagger specifications and integrate this generation into existing processes.

The NSwag project heavily uses NJsonSchema for .NET for JSON Schema handling and C#/TypeScript class/interface generation.

Ways to use the toolchain:

• Simple to use Windows GUI, NSwagStudio
• In your C# code, via NuGet
• Via command line (Windows, Mac and Linux support through Mono)
• Generate code with T4 templates in Visual Studio
• In your MSBuild targets

Swagger Generators:

• ASP.NET Web API assembly to Swagger (supports .NET Core)
  • WebApiToSwaggerGenerator
  • WebApiAssemblyToSwaggerGenerator
• Types from .NET assemblies
  • AssemblyTypeToSwaggerGenerator

Code Generators:

• TypeScript Client
  • SwaggerToTypeScriptClientGenerator
  • Available templates/supported libraries:
    • JQuery with Callbacks, JQueryCallbacks
    • JQuery with promises JQueryPromises
    • AngularJS using $http, AngularJS
    • Angular 2 using the http service, Angular2
• CSharp Client
  • SwaggerToCSharpClientGenerator
  • With INotifyPropertyChanged supporting DTOs
• CSharp WebAPI Controllers (contract first/schema first development)
  • SwaggerToCSharpControllerGenerator
    • Generates Web API Controllers based on a Swagger specification

Downloads

• Download latest NSwagStudio MSI installer (Windows Desktop application)
• Download latest NSwag command line tools and NSwagStudio as ZIP archive
• Download latest Build Artifacts from AppVeyor (command line tools and NSwagStudio binaries)

NuGet Packages

• NSwag.Core (PCL 259): The Swagger reader and writer classes (Source Code)
• NSwag.Annotations (PCL 259): Attributes to decorate Web API controllers to control the Swagger generation (Source Code)
• NSwag.CodeGeneration (PCL 259): Classes to generate C# and TypeScript clients (Source Code)
• NSwag.AssemblyLoader (.NET 4.5+): Classes to load assemblies in an isolated AppDomain and generate Swagger specs from Web API controllers
• 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

Usage in C#

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

var swaggerSettings = new WebApiToSwaggerGeneratorSettings();
var swaggerGenerator = new WebApiToSwaggerGenerator(swaggerSettings);

var service = swaggerGenerator.GenerateForController<PersonsController>();

var clientSettings = new SwaggerToCSharpClientGeneratorSettings 
{
    ClassName = "MyClass",
    Namespace = "MyNamespace"
};
var clientGenerator = new SwaggerToCSharpClientGenerator(service, 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: