Skip to content
Rico Suter edited this page Nov 16, 2018 · 138 revisions

Roadmap | SDK Development | Contribute

Ways to use the toolchain

ASP.NET (Core) Middlewares:

Automated/CLI:

GUI:

Tutorials

Swagger/OpenAPI Document

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:

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:

Customizations