Skip to content
/ NSwag Public
forked from RicoSuter/NSwag

The Swagger API toolchain for .NET, Web API and TypeScript.

License

Notifications You must be signed in to change notification settings

minichma/NSwag

 
 

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

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

NuGet Version npm Build status Build status Gitter StackOverflow ![Donate](https://img.shields.io/badge/donate-via PayPal-green.svg?style=flat)

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 tool chain. 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

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 Swagger specifications from Web API controllers and 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.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+): OWIN Middlewares for serving Swagger specifications and Swagger UI
  • NSwag.AspNet.WebApi (.NET 4.5+): ASP.NET Web API filter which serializes exceptions (JsonExceptionFilterAttribute)
  • NSwagStudio (Chocolatey, Windows): Package to install the NSwagStudio and command line tools via Chocolatey
  • NSwag.Commands (PCL 259): Commands for the command line tool implementations and UI
  • NSwag.ConsoleCore (PCL 259): Command line tool for .NET Core (dotnet nswag)

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 = swaggerGenerator.GenerateForController<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:

About

The Swagger API toolchain for .NET, Web API and TypeScript.

Resources

License

Stars

Watchers

Forks

Packages

No packages published

Languages

  • C# 97.9%
  • TypeScript 1.5%
  • Batchfile 0.4%
  • JavaScript 0.1%
  • PowerShell 0.1%
  • HTML 0.0%