How to generate API clients using msbuild from a remote Swagger Url?

Question

Here's an example URL: https://petstore.swagger.io/

I'm looking for a code sample that solves the problem and industry standard answers to the questions below:

How can I generate a C# API Client using NSwag against this swagger.json endpoint / at build time with MSBuild / dotnet build. Please note that I'm not interested in copying this as a local file and generate it; I'm looking to point to this endpoint specifically.
Why / Why not commit the generated API Client to the repository? Should we let the build generate a new client through the CI/CD build machines on every build?
Is generating the API Clients against live endpoints a good idea in general? What problems did arise for people?

Vasek Vasek · Accepted Answer · 2020-11-20T09:49:05

About how generate client:

I know two methods

The first is to use visual studio function "Connected Services":

Right click one thee project -> Add -> Connected Services. And setup new service(see screenshot for example). I not found any documentation about how user can setup generated code. but you can try, and maybe this will be enough for you task.

The second is to use Nswag directly:

Csproj

<Project Sdk="Microsoft.NET.Sdk">

  <PropertyGroup>
    <OutputType>Exe</OutputType>
    <TargetFramework>netcoreapp3.1</TargetFramework>
  </PropertyGroup>

  <ItemGroup>
    <PackageReference Include="NSwag.AspNetCore" Version="13.9.4" />
    <PackageReference Include="NSwag.MSBuild" Version="13.9.4">
      <PrivateAssets>all</PrivateAssets>
      <IncludeAssets>runtime; build; native; contentfiles; analyzers; buildtransitive</IncludeAssets>
    </PackageReference>
  </ItemGroup>

  <Target Name="NSwag" BeforeTargets="PrepareForBuild">

    <PropertyGroup>
      <!--You can change this if you you want keep generated code in repository-->
      <ClientFileOutDir>$(IntermediateOutputPath)</ClientFileOutDir>
      <ClientFile>$(ClientFileOutDir)/Client.cs</ClientFile>
    </PropertyGroup>

    <Exec Command="$(NSwagExe_Core31) run nswag.json /variables:OutFilename=$(ClientFile)" />

    <ItemGroup>
      <Compile Include="$(ClientFile)" />
    </ItemGroup>
  </Target>

</Project>

nswag.json

{
  "runtime": "NetCore31",
  "defaultVariables": null,
  "documentGenerator": {
    "fromDocument": {
      "url": "https://petstore.swagger.io/v2/swagger.json",
      "output": null,
    }
  },
  "codeGenerators": {
    "openApiToCSharpClient": {
      "output": "$(OutFilename)",
      "className": "PetstoreApi",
      "namespace": "MyNamespace",

      
      /*
      Other properties
      */
    }
  }
}

About generate client or not and live endpoints:

I don't think there is a industry standard for this questions. Rather, you need to proceed from the requirements of the task and your convenience. For example, if in the future an offline build may be needed, then "live endpoints" will not work. Or if the api are constant and do not change, then the generation for each build looks unnecessary and it may be worth generating the client once and placing it in the repository.

How to generate API clients using msbuild from a remote Swagger Url?

1 Answers