Skip to content
Rico Suter edited this page Nov 13, 2019 · 138 revisions

Roadmap | SDK Development | Contribute

Ways to use the toolchain

ASP.NET (Core) Middlewares:

Automated/CLI:

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

Swagger/OpenAPI Document

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:

Customizations

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.

Code Generation

  • Templates: Modify or extend the code generator templates.

Available code generators:

Customizations