Home

Roadmap | SDK Development | Contribute

Ways to use the toolchain

ASP.NET (Core) Middlewares:

• ASP.NET HTTP Middlewares
  • ASP.NET Core Middleware (based on AspNetCoreToSwaggerGenerator)
  • OWIN Middleware (based on WebApiToSwaggerGenerator)
    • How to use the OWIN Middlewares in Global.asax
  • Enable full exception serialization (JsonExceptionFilterAttribute)

Automated/CLI:

• Run as part of the MSBuild process
• Command Line (via NPM or MSI Installer)
• (T4 templates) (outdated, not recommended)

GUI:

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

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
• Implement a custom operation processor to define ReDoc code samples

Swagger/OpenAPI Document

• SwaggerDocument class: The .NET class describing a Swagger specification
• OpenApi 3 support
• YAML support

NSwag builds on top of NJsonSchema and thus most of its settings, extension points, etc. also apply.

Swagger Generation

Available Swagger generators:

• AspNetCoreToSwaggerGenerator (ASP.NET Core only):
  • Generate a Swagger specification from ASP.NET Core controllers via API Explorer
  • UseSwaggerWithApiExplorer(), UseSwaggerUi3WithApiExplorer(), etc.
• WebApiToSwaggerGenerator (supports ASP.NET and ASP.NET Core):
  • Generate a Swagger specification for Web API controller classes (Reflection based):
  • UseSwagger(), UseSwaggerUi3(), etc.
  • Assembly loading instructions (required for CLI usage)

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

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

Customizations

Swagger generation:

You can customize the Swagger generator with the following extension points of NSwag:

• Document Processors and Operation Processors

Schema processing:

• 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
• Schema Name Generators (NJsonSchema): Customize the names of schema 'definitions' keys.

Code Generation

• Templates: Modify or extend the code generator templates.

Available code generators:

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

Customizations

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