The Swagger (Open API) toolchain for .NET, Web API and TypeScript.
C# TypeScript Batchfile JavaScript PowerShell HTML
Switch branches/tags
NSwag-Build-827 NSwag-Build-825 NSwag-Build-822 NSwag-Build-820 NSwag-Build-817 NSwag-Build-815 NSwag-Build-813 NSwag-Build-811 NSwag-Build-809 NSwag-Build-807 NSwag-Build-805 NSwag-Build-801 NSwag-Build-799 NSwag-Build-796 NSwag-Build-794 NSwag-Build-793 NSwag-Build-792 NSwag-Build-791 NSwag-Build-789 NSwag-Build-787 NSwag-Build-785 NSwag-Build-783 NSwag-Build-781 NSwag-Build-779 NSwag-Build-777 NSwag-Build-775 NSwag-Build-774 NSwag-Build-771 NSwag-Build-769 NSwag-Build-767 NSwag-Build-765 NSwag-Build-763 NSwag-Build-761 NSwag-Build-754 NSwag-Build-753 NSwag-Build-751 NSwag-Build-749 NSwag-Build-748 NSwag-Build-746 NSwag-Build-744 NSwag-Build-742 NSwag-Build-740 NSwag-Build-738 NSwag-Build-736 NSwag-Build-734 NSwag-Build-731 NSwag-Build-730 NSwag-Build-729 NSwag-Build-728 NSwag-Build-725 NSwag-Build-723 NSwag-Build-721 NSwag-Build-719 NSwag-Build-717 NSwag-Build-715 NSwag-Build-713 NSwag-Build-711 NSwag-Build-709 NSwag-Build-707 NSwag-Build-705 NSwag-Build-703 NSwag-Build-701 NSwag-Build-699 NSwag-Build-696 NSwag-Build-693 NSwag-Build-691 NSwag-Build-689 NSwag-Build-687 NSwag-Build-685 NSwag-Build-683 NSwag-Build-681 NSwag-Build-679 NSwag-Build-677 NSwag-Build-675 NSwag-Build-673 NSwag-Build-671 NSwag-Build-669 NSwag-Build-667 NSwag-Build-666 NSwag-Build-665 NSwag-Build-664 NSwag-Build-663 NSwag-Build-662 NSwag-Build-661 NSwag-Build-660 NSwag-Build-659 NSwag-Build-658 NSwag-Build-657 NSwag-Build-655 NSwag-Build-645 NSwag-Build-642 NSwag-Build-639 NSwag-Build-637 NSwag-Build-634 NSwag-Build-632 NSwag-Build-627 NSwag-Build-624 NSwag-Build-620 NSwag-Build-617 NSwag-Build-612
Nothing to show
Latest commit 7bfc708 Apr 27, 2017 @rsuter rsuter committed on GitHub Update README.md

README.md

NSwag: The Swagger (Open API) toolchain for .NET, Web API and TypeScript

NuGet Version npm Build status Build status MyGet CI Gitter StackOverflow

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

The project combines the functionality of Swashbuckle (Swagger generation) and AutoRest (client generation) in one toolchain. This way a lot of incompatibilites can be avoided and features which are not well described by the Swagger 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.

Ways to use the toolchain:

Tutorials

Swagger Generators:

Code Generators:

  • TypeScript Client
    • SwaggerToTypeScriptClientGenerator
      • Generates TypeScript clients from a Swagger specification
      • Available templates/supported libraries:
        • JQuery with Callbacks, JQueryCallbacks
        • JQuery with promises JQueryPromises
        • AngularJS using $http, AngularJS
        • Angular 2 using the http service, Angular2
        • 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)
  • CSharp Client
  • CSharp WebAPI Controllers (contract first/schema first development)

Downloads

NPM Packages

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

NuGet Packages

  • NSwag.Core (PCL 259 / .NETStandard 1.0):
    • The Swagger reader and writer classes
  • NSwag.Annotations (PCL 259 / .NETStandard 1.0):
    • Attributes to decorate Web API controllers to control the Swagger generation
  • NSwag.SwaggerGeneration (PCL 259 / .NETStandard 1.0):
    • Classes to generate Swagger specifications
  • NSwag.SwaggerGeneration.WebApi (PCL 259 / .NETStandard 1.0):
    • Classes to generate Swagger specifications from Web API controllers
  • NSwag.CodeGeneration (PCL 259 / .NETStandard 1.0):
    • Base classes to generate clients from Swagger specifications
  • NSwag.CodeGeneration.CSharp (PCL 259 / .NETStandard 1.0):
    • Classes to generate C# clients from Swagger specifications
  • NSwag.CodeGeneration.TypeScript (PCL 259 / .NETStandard 1.0):
    • Classes to generate TypeScript clients from Swagger specifications
  • NSwag.AssemblyLoader (.NET 4.5+):
    • Classes to load assemblies in an isolated AppDomain and generate Swagger specs from Web API controllers
  • NSwag.AssemblyLoaderCore (.NET Core, .NETStandard 1.6):
    • Classes to load assemblies in an AssemblyLoaderContext 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
  • NSwag.AspNetCore (.NETStandard 1.6 and .NET 4.5.1+):
  • NSwag.AspNet.Owin (.NET 4.5+):
    • ASP.NET Core/OWIN middlewares for serving Swagger specifications and Swagger UI
  • NSwag.AspNet.WebApi (.NET 4.5+):
  • NSwagStudio (Chocolatey, Windows):
    • Package to install the NSwagStudio and command line tools via Chocolatey
  • NSwag.Commands (PCL 259 / .NETStandard 1.0):
    • Commands for the command line tool implementations and UI
  • NSwag.ConsoleCore (PCL 259 / .NETStandard 1.0):
    • Command line tool for .NET Core (dotnet nswag)

CI NuGet Feed: https://www.myget.org/gallery/nswag-ci

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

LayerDiagram

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 document = await swaggerGenerator.GenerateForControllerAsync<PersonsController>();

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