OpenApi Doc zu Proxy

Kurzantwort 
 
 NSwag bekommst du als Windows‑GUI (NSwagStudio), als CLI und als NuGet/MSBuild-Integration. Download/Installationswege siehe unten. 
 „Lists statt Arrays“ stellst du über die Generator‑Settings ein (arrayType/arrayInstanceType/responseArrayType/parameterArrayType). Beispiel‑nswag.json ist weiter unten. 
 
 Wo bekomme ich NSwag her? 
 
 NSwagStudio (GUI + CLI inklusive): auf GitHub unter “Releases/Downloads” – MSI oder ZIP (xcopy). ( github.com ) 
 NSwag.MSBuild (für automatische Generierung beim Build): NuGet‑Paket NSwag.MSBuild in dein Projekt einbinden. ( nuget.org , github.com ) 
 Alternativ: CLI als .NET‑Tool/ZIP; allgemeine Befehle/Kommandos siehe Doku. ( github.com ) 
 Offizielle Einstiegshilfe von Microsoft (Codegen‑Optionen, NSwagStudio, NuGet, CLI): ( learn.microsoft.com ) 
 
 Beispiel: C#‑Client mit List<T> statt T[]
Variante A: nswag.json (empfohlen, reproduzierbar) 
 
 Lege neben dein Projekt eine nswag.json und rufe sie via NSwagStudio („Generate Outputs“) oder per CLI/MSBuild auf. 
 
 Beispieldatei (wichtige Stellen markiert) 
 {
 "documentGenerator": {
 "fromDocument": {
 "url": "https://example.local/swagger/v1/swagger.json",
 "output": null,
 "newLineBehavior": "Auto"
 }
 },
 "codeGenerators": {
 "openApiToCSharpClient": {
 "namespace": "MyCompany.MyApiClient",
 "className": "{controller}Client",
 "generateClientClasses": true,
 "generateClientInterfaces": true,
 "injectHttpClient": true,
 "disposeHttpClient": false,
 "useBaseUrl": false,

 // WICHTIG: Lists statt Arrays
 "arrayType": "System.Collections.Generic.List",
 "arrayInstanceType": "System.Collections.Generic.List",
 "responseArrayType": "System.Collections.Generic.List",
 "parameterArrayType": "System.Collections.Generic.IEnumerable",

 // weitere sinnvolle Defaults für .NET Framework 4.8
 "jsonLibrary": "NewtonsoftJson",
 "classStyle": "Poco",
 "generateDefaultValues": true,
 "generateDataAnnotations": true,

 "output": "Generated\\MyApiClient.g.cs",
 "newLineBehavior": "Auto"
 }
 }
}
 
 
 Die Settings arrayType/arrayInstanceType/responseArrayType/parameterArrayType sind offiziell Teil der NSwag/NJsonSchema‑Generator‑Konfiguration. In der „NSwag Configuration Document“-Doku findest du diese Felder (dort z. T. mit anderen Beispieltpyen); du setzt sie einfach auf List bzw. IEnumerable wie oben. ( github.com , stackoverflow.com ) 
 Tipp: Für Methodenparameter ist IEnumerable<T> flexibel, Rückgaben/DTO‑Eigenschaften als List<T> erfüllen „List statt Array“. 
 
 Aufruf 
 
 Per CLI (aus Projektordner):
 
 nswag run .\nswag.json 
 
 
 Per MSBuild automatisch (z. B. nach dem Build): 
 
 <!-- In der .csproj des .NET Framework 4.8-Projekts -->
<ItemGroup>
 <PackageReference Include="NSwag.MSBuild" Version="14.4.0">
 <PrivateAssets>all</PrivateAssets>
 </PackageReference>
</ItemGroup>

<Target Name="NSwag" AfterTargets="Build">
 <Exec Command="$(NSwagExe) run nswag.json" />
</Target>
 
 
 NSwag.MSBuild stellt die Variable $(NSwagExe) bereit, die das passende nswag‑Tool aufruft. ( github.com ) 
 
 Variante B: Direkt über die CLI ohne nswag.json 
 
 Du kannst die wichtigsten Optionen auch als Schalter setzen, z. B.: 
 
 nswag openapi2csclient ^
 /input:https://example.local/swagger/v1/swagger.json ^
 /output:Generated\Client.g.cs ^
 /namespace:MyCompany.MyApiClient ^
 /ArrayType:"System.Collections.Generic.List" ^
 /ArrayInstanceType:"System.Collections.Generic.List" ^
 /ResponseArrayType:"System.Collections.Generic.List" ^
 /ParameterArrayType:"System.Collections.Generic.IEnumerable"
 
 
 Die verfügbaren Kommandos/Parameter sind in der CommandLine‑Doku beschrieben; die oben gezeigten Typ‑Optionen entsprechen den nswag.json‑Feldern aus der Config‑Doku. ( github.com ) 
 
 Variante C: NSwagStudio (GUI) 
 
 Swagger‑URL eintragen, Tab „CSharp Client“ öffnen und bei „Array Type“/„Array Instance Type“ List eintragen; generieren. NSwagStudio kann die Konfiguration als nswag.json speichern. ( github.com ) 
 
 Server‑Stubs (falls du „API“ im Sinne von Controller‑Gerüst meintest) 
 
 NSwag kann auch Controller aus einem OpenAPI‑Dokument erzeugen (ASP.NET Web API 2 für .NET Framework). In der Config nutzt du statt openApiToCSharpClient den Generator openApiToCSharpController, und kannst arrayType etc. identisch setzen; für klassisches Web API ist das aspNetNamespace typischerweise "System.Web.Http". ( github.com ) 
 
 Kompatibilität .NET Framework 4.8 
 
 Die Kernpakete (NSwag.Core/NSwag.Generation/NSwag.AspNetCore) und NSwag.MSBuild unterstützen .NET Framework ≥4.6.2 – damit funktioniert 4.8 problemlos. ( www-1.nuget.org , feed.nuget.org , packages.nuget.org ) 
 
 Zusätzliche Hinweise 
 
 Serializer: Für .NET Framework ist Newtonsoft.Json die pragmatische Wahl. Du kannst über jsonLibrary zwischen NewtonsoftJson und System.Text.Json wechseln (siehe Microsoft‑Blogbeitrag mit Beispiel). ( devblogs.microsoft.com ) 
 Best Practices: Auch wenn du List<T> erzwingst, sind für Parameter IEnumerable<T> und für öffentliche APIs häufig IReadOnlyList<T>/ICollection<T> sinnvoller. Wenn du aber explizit „List überall“ willst, setze responseArrayType ebenfalls auf List wie oben. 
 
 Wenn du mir deine Swagger/OpenAPI‑URL gibst, kann ich dir eine passende nswag.json mit genau den richtigen Settings für dein Projekt (.NET 4.8, Namespace, Dateinamen, usw.) vorbereiten.