Home

Roadmap | SDK Development | Contribute

Ways to use the toolchain

ASP.NET (Core) Middlewares:

• ASP.NET Core Middleware (based on AspNetCoreOpenApiDocumentGenerator)
• OWIN Middleware (based on WebApiOpenApiDocumentGenerator)
  • 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/OpenAPI specification via URL or from a .NET assembly (no running web app needed)

Tutorials

• 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
• ASP.NET Core API with multiple versions, OpenAPI generation and Azure API Management
• A How-To: Generating the Service Client Proxy code

Swagger/OpenAPI Document

• OpenApiDocument 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/OpenAPI Generation

Available Swagger generators:

• AspNetCoreOpenApiDocumentGenerator (ASP.NET Core only):
  • Generate a Swagger/OpenAPI specification from ASP.NET Core controllers via API Explorer
  • AddOpenApiDocument(), AddSwaggerDocument(), etc.
  • UseOpenApi(), UseSwaggerUi3(), UseReDoc(), etc.
• WebApiOpenApiDocumentGenerator (supports ASP.NET and ASP.NET Core, deprecated):
  • Generate a Swagger specification for Web API controller classes (Reflection based):
  • UseSwagger(), UseSwaggerUi3(), etc.
  • Assembly loading instructions (required for CLI usage)

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

• JsonSchemaGenerator (NJsonSchema): Generates schemas from .NET classes
  • Supported C# attributes
• 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/OpenAPI generation:

You can customize the Swagger/OpenAPI 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:

• TypeScriptClientGenerator: Generate TypeScript clients
• CSharpClientGenerator: Generate CSharp clients
• CSharpControllerGenerator: 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.