NSwag — OpenAPI Toolchain for .NET

Introduction

NSwag is an open-source toolchain for the OpenAPI/Swagger specification in the .NET ecosystem. It generates OpenAPI documents from ASP.NET controllers at runtime or build time and produces strongly typed API clients for C# and TypeScript, closing the loop between API definition and consumption.

What NSwag Does

• Generates OpenAPI 3.0 and Swagger 2.0 specifications from ASP.NET code
• Produces C# and TypeScript HTTP client code from any OpenAPI document
• Serves an interactive Swagger UI and ReDoc page for API exploration
• Runs as a CLI tool, MSBuild task, or middleware in ASP.NET Core
• Supports custom document processors and operation filters for advanced scenarios

Architecture Overview

NSwag uses .NET reflection and Roslyn analysis to inspect controller actions, their parameters, and return types. It maps these to OpenAPI schema objects and serializes the result as JSON or YAML. The code generator reads an OpenAPI document, resolves references, and emits client classes using configurable templates. Both directions share a common in-memory OpenAPI model.

Self-Hosting & Configuration

• Add NSwag.AspNetCore to register middleware for spec generation and UI
• Use the NSwag Studio GUI on Windows to configure code generation visually
• Create an nswag.json configuration file for reproducible CLI builds
• Customize generated code with settings for namespaces, base classes, and null handling
• Integrate into CI with the dotnet-nswag tool or MSBuild targets

Key Features

• Bidirectional: spec from code and code from spec in one toolchain
• TypeScript client generation with support for Angular, Axios, Fetch, and jQuery
• Extensible document and operation processors for custom conventions
• NSwag Studio desktop app for visual configuration and preview
• Active maintenance with regular releases tracking .NET and OpenAPI updates

Comparison with Similar Tools

• Swashbuckle — generates OpenAPI specs for ASP.NET but does not produce client code
• OpenAPI Generator — multi-language client generation but not .NET-native
• AutoRest — Microsoft Azure-focused client generator, heavier setup
• Kiota — newer Microsoft HTTP client generator with a different architecture
• Refitter — lightweight .NET source generator for Refit clients from OpenAPI

FAQ

Q: Can NSwag generate clients from third-party APIs? A: Yes. Point the CLI or Studio at any valid OpenAPI JSON or YAML URL to generate a C# or TypeScript client.

Q: Does it support .NET 8 and minimal APIs? A: Yes. Recent versions support minimal API endpoints and the latest .NET releases.

Q: How does it compare to Swashbuckle? A: Swashbuckle focuses on spec generation and Swagger UI. NSwag adds client code generation and the NSwag Studio GUI on top of similar spec generation capabilities.

Q: Can I customize the generated code? A: Yes. NSwag exposes settings for class names, namespaces, exception handling, and Liquid templates for full output control.

Sources

• https://github.com/RicoSuter/NSwag
• https://github.com/RicoSuter/NSwag/wiki