Skip to content

Latest commit

 

History

History
245 lines (178 loc) · 16 KB

README.md

File metadata and controls

245 lines (178 loc) · 16 KB
Raw

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

NuGet Version npm Build status MyGet Gitter StackOverflow Wiki Backers on Open Collective Sponsors on Open Collective

NSwag v12 released!

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

Features:

Ways to use the toolchain:

Tutorials:

Swagger Generators:

Code Generators:

  • CSharp Client
    • SwaggerToCSharpClientGenerator
      • Generates C# clients from a Swagger 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)
  • 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 (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 (.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 Swagger specifications
  • NSwag.Annotations (.NET Standard 1.0 / 2.0 and .NET 4.5):
    • Attributes to decorate Web API controllers to control the Swagger generation

Swagger 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 Swagger 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/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#

To register the middlewares to generate a Swagger 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.UseSwagger(); // serve OpenAPI/Swagger documents
        app.UseSwaggerUi3(); // serve Swagger UI
	app.UseReDoc(); // serve ReDoc UI
    }
}

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",
    CSharpGeneratorSettings = 
    {
        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:

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.

Sponsors:

Contributors

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

Backers

Thank you to all our backers! 🙏 [Become a backer]

Sponsors

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