RicoSuter/NSwag - TS 中文文档

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

NSwag | NJsonSchema | Apimundo | Namotion.Reflection

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

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.

Features:

Generate Swagger 2.0 and OpenAPI 3.0 specifications from C# ASP.NET (Core) controllers

Serve the specs via ASP.NET (Core) middleware, optionally with Swagger UI or ReDoc

Generate C# or TypeScript clients/proxies from these specs

Everything can be automated via CLI (distributed via NuGet tool or build target; or NPM)

CLI configured via JSON file or NSwagStudio Windows UI

Ways to use the toolchain:

Simple to use Windows GUI, NSwagStudio

By using the OpenAPI or OpenAPI UI OWIN and ASP.NET Core Middlewares (also serves the Swagger UI ) (recommended)

Via command line (Windows, Mac and Linux support through Mono or .NET Core console binary, also via NPM package )

In your C# code, via NuGet

In your MSBuild targets

With ServiceProjectReference tags in your .csproj (preview)

In your Azure V2 Functions (external project, might not use latest NSwag version)

Tutorials:

Add NSwag to your ASP.NET Core app

Integrate the NSwag toolchain into your ASP.NET Web API project

Generate an Angular TypeScript client from an existing ASP.NET Web API web assembly

Video Tutorial: How to integrate NSwag into your ASP.NET Core Web API project (5 mins)

OpenAPI/Swagger Generators:

ASP.NET Web API assembly to OpenAPI (supports .NET Core)

AspNetCoreOpenApiDocumentGenerator

WebApiOpenApiDocumentGenerator

Generates an OpenAPI specification for Web API controllers

WebApiToOpenApiCommand

Generates an OpenAPI specification for controllers in an external Web API assembly

Also supports loading of .NET Core assemblies

TypesToOpenApiCommand

Generates an OpenAPI specification containing only types from .NET assemblies

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)

CSharpControllerGenerator

Generates Web API Controllers based on a OpenAPI specification (ASP.NET Web API and ASP.NET Core)

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)

Downloads

Download latest NSwagStudio MSI installer (NSwagStudio.msi) (Windows Desktop application)

Download latest NSwag command line tools and NSwagStudio (NSwag.zip)

NPM Packages

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

NuGet Packages

Specification:

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:

NSwag.Generation * (.NET Standard 1.0 / 2.0 and .NET 4.5)

Classes to generate OpenAPI specifications

NSwag.Generation.WebApi * (.NET Standard 1.0 / 2.0 and .NET 4.5)

Classes to generate OpenAPI specifications from Web API controllers, see WebApiOpenApiDocumentGenerator

NSwag.Generation.AspNetCore * (.NET Standard 1.6 / 2.0 and .NET 4.5.1)

(Experimental) Classes to generate OpenAPI specifications from ASP.NET Core MVC controllers using the ApiExplorer

Code generation:

NSwag.CodeGeneration * (.NET Standard 1.3 / 2.0 / .NET 4.5.1)

Base classes to generate clients from OpenAPI specifications

NSwag.CodeGeneration.CSharp * (.NET Standard 1.3 and .NET 4.5.1)

Classes to generate C# clients from OpenAPI specifications, see CSharpClientGenerator and CSharpControllerGenerator

NSwag.CodeGeneration.TypeScript * (.NET Standard 1.3 and .NET 4.5.1)

Classes to generate TypeScript clients from OpenAPI specifications, see TypeScriptClientGenerator

ASP.NET and ASP.NET Core:

NSwag.AspNetCore * (.NET Standard 1.6 / 2.0 and .NET 4.5.1+)

NSwag.AspNet.Owin * (.NET 4.5+)

ASP.NET Core/OWIN middlewares for serving OpenAPI specifications and Swagger UI

NSwag.AspNet.WebApi * (.NET 4.5+)

ASP.NET Web API filter which serializes exceptions (JsonExceptionFilterAttribute )

Frontends:

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 )

NSwagStudio * (Chocolatey, Windows):

Package to install the NSwagStudio and command line tools via Chocolatey

CI NuGet Feed: https://www.myget.org/F/nswag/api/v3/index.json

The NuGet packages may require the Microsoft.NETCore.Portable.Compatibilitypackage 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 :

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

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

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:

Sponsor main contributor Rico Suter via GitHub

Sponsor project via Open Collective for NSwag

Please contact Rico Suter for paid consulting and support.

Contributors

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

Backers

Thank you to all our backers!