如何从远程 Swagger Url 使用 msbuild 生成 API 客户端？

Question

这是一个例子URL：https://petstore.swagger.io/

我正在寻找解决问题的代码示例以及对以下问题的行业标准答案：

如何使用 NSwag 针对此 swagger.json 端点/在构建时使用 MSBuild/dotnet build 生成 C# API 客户端。请注意，我对将其复制为本地文件并生成它不感兴趣；我希望具体指向此端点。
为什么/为什么不将生成的 API 客户端提交到存储库？我们是否应该让构建在每次构建时通过 CI/CD 构建机器生成一个新客户端？
生成针对实时端点的 API 客户端通常是个好主意吗？给人们带来了什么问题？

Answer 1

关于如何生成客户端：

我知道两种方法

首先是使用visual studio功能“连接服务”：

右键单击一个项目 -> 添加 -> 连接服务。并设置新服务（例如，参见屏幕截图）。我没有找到任何关于用户如何设置生成代码的文档。但你可以试试，也许这对你的任务来说已经足够了。

第二种是直接使用Nswag：

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
      */
    }
  }
}

关于是否生成客户端和实时端点：

我认为这个问题没有行业标准。相反，您需要从任务的要求和您的方便出发。例如，如果将来可能需要离线构建，那么“实时端点”将不起作用。或者，如果 api 是常量且不会更改，那么每个构建的生成看起来都是不必要的，可能值得生成一次客户端并将其放入存储库中。

如何从远程 Swagger Url 使用 msbuild 生成 API 客户端？

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

msbuild

swagger

nswag