# ricosuter/nswag architecture

> Architecture diagram of the GitHub repository ricosuter/nswag, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-21). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/ricosuter/nswag
- Repository: https://github.com/ricosuter/nswag

## Overview

##### 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`)

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Presentation & Invocation"
        Studio["NSwagStudio GUI"]:::host
        CLI_Core["dotnet nswag (ConsoleCore)"]:::host
        CLI_Fx["nswag.exe (Console)"]:::host
        MSBuild["NSwag.MSBuild Task"]:::host
        NPM["NSwag NPM Wrapper"]:::host
    end

    Studio -->|"invokes"| Commands["NSwag.Commands\n(Command Processor)"]:::host
    CLI_Core -->|"invokes"| Commands
    CLI_Fx -->|"invokes"| Commands
    MSBuild -->|"invokes"| Commands
    NPM -->|"invokes"| Commands

    subgraph "Core Engine"
        Core["NSwag.Core & NSwag.Core.Yaml"]:::lib
        NJson["NJsonSchema"]:::external
    end

    Commands -->|"uses"| Core
    Core -->|"parses JSON/YAML"| NJson

    subgraph "OpenAPI Generators"
        WebApi["WebApiOpenApiDocumentGenerator"]:::lib
        AspCore["AspNetCoreOpenApiDocumentGenerator"]:::lib
        Types2OpenApi["JsonSchemaToOpenApiCommand"]:::lib
    end

    Core -->|"generates spec"| WebApi
    Core -->|"generates spec"| AspCore
    Commands -->|"generates spec via"| Types2OpenApi

    subgraph "Code Generators"
        CSharpGen["CSharpClient/ControllerGenerator"]:::lib
        TSGen["TypeScriptClientGenerator"]:::lib
    end

    WebApi -->|"feeds spec"| CSharpGen
    AspCore -->|"feeds spec"| CSharpGen
    Types2OpenApi -->|"feeds spec"| CSharpGen
    WebApi -->|"feeds spec"| TSGen
    AspCore -->|"feeds spec"| TSGen
    Types2OpenApi -->|"feeds spec"| TSGen

    subgraph "ASP.NET Runtime Hosting"
        ASPSample["ASP.NET App"]:::runtime
        OwinMid["OWIN Middleware"]:::runtime
        CoreMid["ASP.NET Core Middleware"]:::runtime
        StaticUI["Swagger UI / ReDoc"]:::external
    end

    ASPSample -->|"HTTP request"| OwinMid
    ASPSample -->|"HTTP request"| CoreMid
    OwinMid -->|"calls Core Engine"| Core
    CoreMid -->|"calls Core Engine"| Core
    OwinMid -->|"serves assets"| StaticUI
    CoreMid -->|"serves assets"| StaticUI

    subgraph "Outputs"
        JSONSpec["OpenAPI JSON/YAML"]:::external
        CodeOut["Generated C#/.ts files"]:::external
    end

    WebApi -->|"output spec"| JSONSpec
    AspCore -->|"output spec"| JSONSpec
    CSharpGen -->|"output code"| CodeOut
    TSGen -->|"output code"| CodeOut

    subgraph "Samples & Tests"
        Samples["Sample Applications"]:::external
        Tests["Test Suites"]:::external
    end

    Samples --> Core
    Samples --> CSharpGen
    Samples --> TSGen
    Tests --> Core
    Tests --> WebApi
    Tests --> AspCore
    Tests --> CSharpGen
    Tests --> TSGen

    click Studio "https://github.com/ricosuter/nswag/tree/master/src/NSwagStudio/"
    click CLI_Core "https://github.com/ricosuter/nswag/blob/master/src/NSwag.ConsoleCore/Program.cs"
    click CLI_Fx "https://github.com/ricosuter/nswag/blob/master/src/NSwag.Console/Program.cs"
    click MSBuild "https://github.com/ricosuter/nswag/blob/master/src/NSwag.MSBuild/NSwag.MSBuild.props"
    click MSBuild "https://github.com/ricosuter/nswag/blob/master/src/NSwag.MSBuild/NSwag.MSBuild.nuspec"
    click NPM "https://github.com/ricosuter/nswag/tree/master/src/NSwag.Npm/"
    click Commands "https://github.com/ricosuter/nswag/blob/master/src/NSwag.Commands/NSwagCommandProcessor.cs"
    click WebApi "https://github.com/ricosuter/nswag/blob/master/src/NSwag.Generation.WebApi/WebApiOpenApiDocumentGenerator.cs"
    click AspCore "https://github.com/ricosuter/nswag/blob/master/src/NSwag.Generation.AspNetCore/AspNetCoreOpenApiDocumentGenerator.cs"
    click Types2OpenApi "https://github.com/ricosuter/nswag/blob/master/src/NSwag.Commands/Commands/CodeGeneration/JsonSchemaToOpenApiCommand.cs"
    click CSharpGen "https://github.com/ricosuter/nswag/blob/master/src/NSwag.CodeGeneration.CSharp/CSharpClientGenerator.cs"
    click CSharpGen "https://github.com/ricosuter/nswag/blob/master/src/NSwag.CodeGeneration.CSharp/CSharpControllerGenerator.cs"
    click TSGen "https://github.com/ricosuter/nswag/blob/master/src/NSwag.CodeGeneration.TypeScript/TypeScriptClientGenerator.cs"
    click OwinMid "https://github.com/ricosuter/nswag/blob/master/src/NSwag.AspNet.Owin/Middlewares/OpenApiDocumentMiddleware.cs"
    click CoreMid "https://github.com/ricosuter/nswag/blob/master/src/NSwag.AspNetCore/Middlewares/OpenApiDocumentMiddleware.cs"
    click StaticUI "https://github.com/ricosuter/nswag/tree/master/src/NSwag.AspNetCore/SwaggerUi/"
    click StaticUI "https://github.com/ricosuter/nswag/blob/master/src/NSwag.AspNetCore/ReDoc/index.html"
    click StaticUI "https://github.com/ricosuter/nswag/tree/master/src/NSwag.AspNet.Owin/SwaggerUi/"
    click StaticUI "https://github.com/ricosuter/nswag/blob/master/src/NSwag.AspNet.Owin/ReDoc/index.html"

    classDef lib fill:#ADD8E6,stroke:#000,color:#000
    classDef host fill:#90EE90,stroke:#000,color:#000
    classDef runtime fill:#FFA500,stroke:#000,color:#000
    classDef external fill:#D3D3D3,stroke:#000,color:#000
```
