explaingit

ricosuter/nswag

★ 7,329C#Audience · developerComplexity · 3/5Setup · moderate

TLDR

A .NET toolset that reads your ASP.NET Core web API and automatically generates OpenAPI documentation and ready-to-use client code in C# or TypeScript, so you never write API client code by hand.

Mindmap

mindmap
  root((repo))
    What it does
      API documentation
      Client generation
      .NET toolchain
    Output
      OpenAPI spec
      C# clients
      TypeScript clients
    Frameworks Supported
      ASP.NET Core
      Angular
      React
    Usage Options
      NSwag Studio
      Command line
      MSBuild
Click or tap to explore — scroll the page freely

Code map

Detail Auto

An interactive map of this repo's files and how they connect — its source is parsed live in your browser. Click Visualize to build it.

filefunction / class

Things people build with this

USE CASE 1

Generate a TypeScript client for your React frontend from your ASP.NET Core API without writing any client code by hand

USE CASE 2

Add an interactive API documentation browser to your .NET web app with a single middleware line so developers can explore endpoints in the browser

USE CASE 3

Automate TypeScript and C# client regeneration as part of a CI/CD build pipeline using MSBuild targets so clients always match the API

Tech stack

C#.NETASP.NET CoreTypeScriptNuGetMSBuild

Getting it running

Difficulty · moderate Time to first run · 30min

Requires .NET SDK, CLI tool works cross-platform but NSwagStudio GUI is Windows-only.

In plain English

NSwag is a set of tools for .NET developers that automates two related tasks: describing how a web API works, and generating the code needed to call it from other applications. When you build a web API in .NET or ASP.NET Core (Microsoft's frameworks for building websites and services), NSwag can read your existing code and produce an OpenAPI (formerly called Swagger) specification. This is a standardized document that describes every endpoint your API offers, what inputs each one expects, and what it returns. The document acts as a machine-readable contract that other tools can consume. From that contract, NSwag generates ready-to-use client code in C# or TypeScript. Instead of writing by hand the code that calls your API from a website or another service, NSwag writes it for you. TypeScript clients are available for several popular frontend frameworks including Angular, AngularJS, React (via the Fetch template), and Aurelia. C# clients can be used in regular .NET apps.NET Core, and Xamarin for mobile apps. The toolchain runs several ways: through NSwagStudio, a Windows desktop application with a graphical interface, via a command line tool that works on Windows, Mac, and Linux, directly in C# code via NuGet packages, or as part of an automated build process through MSBuild targets. ASP.NET Core projects can add a middleware layer that serves the generated documentation page and an interactive browser UI alongside the running application, letting developers and consumers of the API explore available endpoints without reading code.

Copy-paste prompts

Prompt 1
I have an ASP.NET Core Web API and I want NSwag to generate a TypeScript fetch client for my React frontend. Show me how to add the NSwag NuGet packages, configure the middleware, and run the CLI to output a TypeScript client file.
Prompt 2
I want to add an interactive Swagger UI page to my running ASP.NET Core API using NSwag middleware. Show me the Program.cs setup code to serve both the OpenAPI spec and the browser UI.
Prompt 3
I want to automate TypeScript client generation in my .NET build so the client file is always regenerated when the API changes. Show me how to configure an MSBuild target in my .csproj file to run NSwag as part of the build.
Open on GitHub → Explain another repo

← ricosuter on gitmyhub — every repo by this author, as a profile.

Verify against the repo before relying on details.