Asp.Net Core Controller mit OpenAPI

Wenn man im Projekt die Situation hat, dass man z.B. zwei unterschiedliche Personen hat, welche einerseits den OpenAPI Contract schreiben und anderseits implementieren, macht es Sinn, den Contract-First Approch zu verfolgen.

Bei .NET geht das nicht so out-of-the-box, wie z.B. bei Spring mit Maven.

Schritt 1: NSwag Studio laden

Das neueste NSwag Studio kann man von hier beziehen: https://github.com/RicoSuter/NSwag/releases. In NSwag kann man den OpenAPI Contract pasten und on-the-fly generieren lassen.

Ein gutes Beispiel bekommt man hier: https://editor-next.swagger.io/

Schritt 2: NSwag Konfiguration exportieren Anschließend kann man per File > Save As die Konfiguration speichern. E.g. unter nswag.json

Schritt 3: Neues Projekt anlegen

dotnet new webapi -o OpenApiExample
cd OpenApiExample
dotnet add package NSwag.MSBuild
dotnet add package Newtonsoft.Json

Schritt 4: Anpassen der project File Folgendes muss in der Project File hinzugefügt werden. Quelle: https://github.com/RicoSuter/NSwag/wiki/NSwag.MSBuild

<PropertyGroup>
    <RunPostBuildEvent>OnBuildSuccess</RunPostBuildEvent>
  </PropertyGroup>
 
  <Target Name="NSwag" AfterTargets="PostBuildEvent" Condition=" '$(Configuration)' == 'Debug' ">
    <Exec WorkingDirectory="$(ProjectDir)" EnvironmentVariables="ASPNETCORE_ENVIRONMENT=Development" Command="$(NSwagExe_Net80) run nswag.json /variables:Configuration=$(Configuration)" />
  </Target>
  
</Project>

Schritt 5: Hinzufügen der OpenAPI Z.B. unter api.yml. Die generierte File kann man z.B. unter Controllers/Pet.g.cs legen.

Ein vollständiges Beispiel gibts hier: https://github.com/mvodep/Playground/tree/main/OpenApiExample

Known-Issues: Anscheinend funktioniert Multi-File Upload Generation nicht ganz https://github.com/RicoSuter/NSwag/issues/2419