Lawrence  Lesch

Lawrence Lesch


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

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

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.


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


Ways to use the toolchain:


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)
  • TypeScript Client
    • TypeScriptClientGenerator
      • Generates TypeScript clients from a 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)


NPM Packages

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

NuGet Packages


  • 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:



  • 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)
    • <DotNetCliToolReference Include="NSwag.ConsoleCore" Version="..." />
  • NSwagStudio (Chocolatey, Windows):
    • Package to install the NSwagStudio and command line tools via Chocolatey

CI NuGet Feed:

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


Usage in C#

To register the middlewares to generate a 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.UseSwaggerUi3(); // 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.


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

NSwag | NJsonSchema | Apimundo | Namotion.Reflection

👉 Announcing Apimundo: An API documentation system based on NSwag and NJsonSchema 👈

Download Details:

Author: RicoSuter
Source Code: 
License: MIT license

#typescript #angular #csharp #aurelia #dotnet 

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

Eric Bukenya


AURELIA Vs REACT Which Is Better for You

The popularity of React is undeniable. When bright-eyed developers think about creating a new app, React is usually the first thing that crosses their minds. React has all become the defacto front-end library of choice.

#react #aurelia 

AURELIA Vs REACT Which Is Better for You

Aurelia Vs AngularJS : Which One To Choose?

In the web development world and javascript world, we’ve seen a lot of paradigms come and go. But one paradigm has stuck around: the single-page web application. AngularJS is one of the most popular frameworks backed by Google, and it offers quick, easy development of rich, client-side applications by the use of declarative two-way data binding. AngularJS is used by popular companies like Amazon and Pluralsight.

Whereas, the Aurelia framework was released a couple months prior to Angular 2, and also serves as a great choice of SPA framework with a quickly growing audience. Aurelia, has become a popular choice for rich, client-side applications. Aurelia targets the same problem space as AngularJS. However, Aurelia uses a modern approach to ease development and solve a lot of the problems that plagued AngularJS.

So What’s the difference between Aurelia and Angular? Before starting comparison, let us see What is Angular and What is Aurelia?


Aurelia was backed by Durandal Inc and was licensed under the MIT license. It is an open-source framework and provides great rendering speed, very good memory efficiency, unidirectional data flow which is safer, higher standards of compliance, greater integration compatibility with different other platforms or frameworks. Deloitte, Chegg, dev and many such popular companies make use of Aurelia. Here are some of the features of Aurelia-

  • Broad Language Support
  • Two-Way Databinding
  • Routing & UI Composition
  • Testable
  • Angular-

AngularJS is a front-end web framework supported by Google. This framework makes use of HTML as your template language and allows you to extend HTML’s syntax to express app’s components more clearly. Amazon, snapchat, Tinder and many more popular brands uses Angular.js. Let us see features of Angular.

  • Templates
  • MVC Framework
  • Access to the POJO Model
  • Unit Testing Facilities

Aurelia vs Angular-

1. MV Approach-*
Aurelia follows the Model-View approach. There is no need to specify the particular controllers of view-models; the naming conventions will do that. For instance-
“AnyFile.html”: Any file loaded under router-view or called at the time of instantiating Aurelia App.
“AnyFile.js”: Controller of the Anyfile.html view-model. export class AnyFile { constructor() { } } When comparing with Angular, you will see the difference in watching MV* components. One of the big disadvantage of AngularJS is that it has a very sheer learning curve. You must know its internals, the complete digest cycle pretty well and have to know the effect on performance while using $watch expressions and filters. Whereas Aurelia is simple and has a smooth learning curve.

2. Language Support-
Know more at-

#angular #aurelia #framework

How To Deploy Aurelia 2 Apps To GitHub Pages (gh-pages)

You have yourself an Aurelia app (or you will soon), and you want to host it on GitHub Pages because GitHub provides a generous free hosting solution that gets powered from the Git repository itself.

Fortunately, the process couldn’t be more straightforward. A lot of this post will apply to other frameworks and libraries besides Aurelia 2. However, we will be focusing on Aurelia 2 only.

This article assumes the following:

You already have a Git repository for your Aurelia project
You are using GitHub to host your Git repository

#aurelia 2 tutorials #github #aurelia

How To Deploy Aurelia 2 Apps To GitHub Pages (gh-pages)