How ricosuter/nswag works
Project Type and Purpose
• NSwag is an open-source toolchain for generating and consuming OpenAPI/Swagger specs in .NET and TypeScript.
• It provides libraries, command-line tools, a GUI (NSwagStudio), MSBuild integration, ASP.NET middlewares, and NPM packaging.
• Core use cases:
• Generate OpenAPI docs from Web API or ASP.NET Core controllers
• Serve those docs at runtime with Swagger UI or ReDoc
• Generate C# or TypeScript clients/controllers from specs
• Automate via CLI, MSBuild, GUI, or NPM
File Structure Analysis
• Top-level CI/build: .github/, azure-pipelines.yml, Nuke/ scripts, build/ folder with C# build definitions.
• Documentation: docs/ and assets/ (ToolchainDiagram.vsdx, LayerDiagram.vsdx).
• Source code (src/):
• Core libraries: NSwag.Core, NSwag.Core.Yaml
• OpenAPI generation: NSwag.Generation, plus Generation.WebApi, Generation.AspNetCore
• Code generation: NSwag.CodeGeneration.CSharp, TypeScript and base CodeGeneration
• Runtime frameworks: NSwag.AspNet.Owin, NSwag.AspNet.WebApi, NSwag.AspNetCore
• Host and tooling: NSwag.Commands, NSwag.ConsoleCore, NSwag.Console, NSwag.MSBuild, NSwag.Npm
• GUI: NSwagStudio (WPF)
• Samples: NSwag.Sample.*
• Tests for each module under *.Tests
• Configuration and packaging: NuGet nuspecs, NPM package.json, MSBuild .props/.targets.
Key Insights from README
• Layered architecture: Core → Generation → CodeGeneration → Front-ends.
• Supports multiple entry points: GUI, CLI, MSBuild, NPM, middleware in ASP.NET.
Components
a. Presentation & Invocation layers
• NSwagStudio GUI (WPF)
• CLI tools (dotnet nswag, nswag.exe)
• MSBuild Task (NSwag.MSBuild)
• NPM wrapper (nswag.js)
b. Host & Orchestration
• NSwag.Commands: command processor invoking generators
• ConsoleCore/Console: .NET Core / full-framework hosts
c. Core Engine
• NSwag.Core & NSwag.Core.Yaml: read/write OpenAPI docs
• NJsonSchema (external dependency, JSON Schema handling)
d. OpenAPI Generators
• WebApiOpenApiDocumentGenerator
• AspNetCoreOpenApiDocumentGenerator
• TypesToOpenApiCommand
e. Code Generators
• CSharpClientGenerator & ControllerGenerator
• TypeScriptClientGenerator (various templates)
f. ASP.NET Middlewares
• OWIN and ASP.NET Core middlewares to serve docs and UI
g. Output
• Swagger UI / ReDoc static assets
• Generated C# and TypeScript files
h. Samples & Tests
• Sample ASP.NET apps consuming NSwag
• Automated test suites validating each module
Relationships and Interactions
• NSwag.Commands calls into Core Engine → Generation modules → CodeGeneration modules
• Feedback loop where user-provided .nswag JSON config drives the pipeline
Architectural Patterns & Design Principles
• Layered architecture with clear separations: Core → Generation → CodeGeneration → Presentation
• Plugin-like command dispatcher (NSwag.Commands) for extensibility
• Multi-host strategy (Console, GUI, MSBuild, NPM) reusing same engine
• Test-driven modules with dedicated test projects
• Modular .NET projects, packaged separately as NuGet/NPM
• Every major submodule under src/ in grouped clusters
• Core Engine and its two I/O concerns (JSON & YAML via NSwag.Core / Yaml)
• Dual Generation branches (WebApi vs. AspNetCore vs. Types)
• CodeGeneration outputs separately for C# and TS, including template layering
• Middleware insertion into ASP.NET pipeline for doc serving and UI
• Blue for libraries
• Green for hosts and scripts
• Orange for runtime ASP.NET components
• Grey for external tools/dependencies
• File-based integrations (e.g., .nswag config, output .json, .cs, .ts)