Home

Roadmap | SDK Development | Contribute

Ways to use the toolchain

• Command Line (via NPM or MSI Installer)
• NSwagStudio (Windows GUI)
  • Edit .nswag configuration files which can be executed via command line
  • Swagger specification via URL or from a .NET assembly (no running web app needed)
• ASP.NET HTTP Middlewares
  • Swagger and Swagger UI OWIN and ASP.NET Core Middlewares
  • How to use the OWIN Middlewares in Global.asax
  • Enable full exception serialization (JsonExceptionFilterAttribute)
• Run as part of the MSBuild process
• T4 templates

Tutorials

• Video Tutorial: How to integrate NSwag into your ASP.NET Core Web API project (5 mins)
• Integrate the NSwag toolchain into your ASP.NET Web API project
• Generate an Angular 2 TypeScript client from an existing ASP.NET Web API web assembly

Specification

• SwaggerDocument class: The .NET class describing a Swagger specification

Swagger Generation

Available Swagger generators:

• WebApiToSwaggerGenerator: Generate a Swagger specification from Web API controller classes
• WebApiAssemblyToSwaggerGenerator: Generate a Swagger specification from a Web API assembly

Customizations and extension points:

The Swagger generators use the JSON Schema generator from the NJsonSchema project:

• Document Processors and Operation Processors
• JsonSchemaGenerator (NJsonSchema): Generates schemas from .NET classes
• XML Documentation (NJsonSchema)
  • The NSwag.AspNetCore NuGet package automatically installs the required NuGet packages for reading XML Documentation.
• Enums (NJsonSchema)
• Inheritance (NJsonSchema): How to describe and generate inheritance of DTO classes.
• Type Mappers (NJsonSchema): Type mappers allow you to generate a custom JSON Schema for a given .NET type.
• Schema Processors (NJsonSchema): Post process the generation of the schema or child schemas

Code Generation

Available code generators:

• SwaggerToTypeScriptClientGenerator: Generate TypeScript clients
• SwaggerToCSharpClientGenerator: Generate CSharp clients
• SwaggerToCSharpControllerGenerator: Generate CSharp Web API controllers (contract first/schema first development)

Extension points:

• Property Name Generators: Customize the generation of property names.
• Schema Name Generators (NJsonSchema): Customize the names of schema 'definitions' keys.
• Type Name Generators (NJsonSchema): Customize the way how C#/TypeScript class or interface names are generated.