-
-
Notifications
You must be signed in to change notification settings - Fork 1.3k
Home
Rico Suter edited this page Nov 13, 2019
·
138 revisions
Roadmap | SDK Development | Contribute
ASP.NET (Core) Middlewares:
- ASP.NET Core Middleware (based on AspNetCoreOpenApiDocumentGenerator)
- OWIN Middleware (based on WebApiOpenApiDocumentGenerator)
- 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)
- 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
- 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.
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
-
XML Documentation (NJsonSchema)
- The
NSwag.AspNetCore
NuGet package automatically installs the required NuGet packages for reading XML Documentation.
- The
- Enums (NJsonSchema)
- Inheritance (NJsonSchema): How to describe and generate inheritance of DTO classes.
Swagger/OpenAPI generation:
You can customize the Swagger/OpenAPI generator with the following extension points of NSwag:
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.
- 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)
- 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.