# 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](https://github.com/RicoSuter/NSwag?utm_source=openai))
- NSwag.MSBuild (für automatische Generierung beim Build): NuGet‑Paket NSwag.MSBuild in dein Projekt einbinden. ([nuget.org](https://www.nuget.org/packages/NSwag.MSBuild?utm_source=openai), [github.com](https://github.com/RicoSuter/NSwag/wiki/NSwag.MSBuild?utm_source=openai))
- Alternativ: CLI als .NET‑Tool/ZIP; allgemeine Befehle/Kommandos siehe Doku. ([github.com](https://github.com/RicoSuter/NSwag/wiki/CommandLine?utm_source=openai))
- Offizielle Einstiegshilfe von Microsoft (Codegen‑Optionen, NSwagStudio, NuGet, CLI): ([learn.microsoft.com](https://learn.microsoft.com/en-us/aspnet/core/tutorials/getting-started-with-nswag?view=aspnetcore-7.0&utm_source=openai))

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)
```json
{
  "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](https://github.com/RicoSuter/NSwag/wiki/NSwag-Configuration-Document?utm_source=openai), [stackoverflow.com](https://stackoverflow.com/questions/76207731/nswag-studio-is-unable-to-handle-a-json-body-with-an-array?utm_source=openai))
- 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):
```xml
<!-- 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](https://github.com/RicoSuter/NSwag/wiki/NSwag.MSBuild?utm_source=openai))

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](https://github.com/RicoSuter/NSwag/wiki/CommandLine?utm_source=openai))

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](https://github.com/RicoSuter/NSwag/wiki/NSwagStudio?utm_source=openai))

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](https://github.com/RicoSuter/NSwag/wiki/NSwag-Configuration-Document?utm_source=openai))

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](https://www-1.nuget.org/packages/NSwag.Core/?utm_source=openai), [feed.nuget.org](https://feed.nuget.org/packages/NSwag.Generation/?utm_source=openai), [packages.nuget.org](https://packages.nuget.org/packages/NSwag.AspNetCore/?utm_source=openai))

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](https://devblogs.microsoft.com/ise/2023/07/25/maintain-api-client-with-nswag-model-gen/?utm_source=openai))
- 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.