.NET 10：如何在编译时通过csproj集成NSwag生成Swagger客户端

步骤1：清理旧配置和包引用 #

• 从你的.csproj文件中移除Microsoft.Extensions.ApiDescription.Client的包引用：

<!-- 删掉这行 -->
<PackageReference Include="Microsoft.Extensions.ApiDescription.Client" Version="x.x.x" PrivateAssets="all" />

• 同时移除原来的<OpenApiReference>配置节点：

<!-- 删掉这类配置 -->
<OpenApiReference Include="swagger.json" CodeGenerator="NSwagCSharp" />

步骤2：安装NSwag命令行工具 #

推荐用本地dotnet工具（避免全局版本冲突），在项目根目录执行：

dotnet tool install NSwag.ConsoleCore --local

执行后会自动生成.config/dotnet-tools.json记录工具版本，需要指定版本就加--version x.x.x参数。

步骤3：创建NSwag配置文件 #

在项目根目录新建ApiClient.nswag文件，配置swagger源、生成规则和输出路径，示例如下：

{
  "runtime": "Net80",
  "documentGenerator": {
    "fromDocument": {
      "url": "https://your-api-url/swagger/v1/swagger.json",
      "newLineBehavior": "Auto"
    }
  },
  "codeGenerators": {
    "csharp": {
      "injectHttpClient": true,
      "generateSyncMethods": false,
      "useStringEnum": true,
      "className": "{controller}Client",
      "namespace": "Your.Project.Namespace",
      "output": "Generated/SwaggerClient.cs",
      "newLineBehavior": "Auto"
    }
  }
}

根据实际需求调整：

• 把url改成你的swagger文档地址（本地文件用file:///$(ProjectDir)swagger.json格式）
• 替换namespace为项目实际命名空间
• 调整output为你想存放生成代码的路径

步骤4：在csproj中集成编译时生成逻辑 #

在.csproj里添加自定义编译目标，确保编译前自动生成代码并纳入编译流程：

<PropertyGroup>
  <NSwagConfig>ApiClient.nswag</NSwagConfig>
  <GeneratedClientPath>Generated/SwaggerClient.cs</GeneratedClientPath>
</PropertyGroup>

<!-- 先创建生成目录，避免报错 -->
<Target Name="CreateGeneratedDirectory" BeforeTargets="GenerateApiClient">
  <MakeDir Directories="$(ProjectDir)Generated" />
</Target>

<!-- 编译前执行NSwag生成代码 -->
<Target Name="GenerateApiClient" BeforeTargets="CoreCompile" Inputs="$(NSwagConfig);$(ProjectDir)swagger.json" Outputs="$(GeneratedClientPath)">
  <Exec Command="dotnet tool run nswag run $(NSwagConfig) /variables:ProjectDir=$(ProjectDir)" />
</Target>

<!-- 将生成的代码加入编译项 -->
<ItemGroup>
  <Compile Include="$(GeneratedClientPath)" />
  <None Include="ApiClient.nswag" />
  <None Include=".config/dotnet-tools.json" />
</ItemGroup>

说明：

• Inputs和Outputs配置可以让工具只在swagger文件或NSwag配置变化时重新生成，提升编译速度
• 如果你的swagger是远程地址，可以去掉Inputs里的$(ProjectDir)swagger.json

验证效果 #

执行dotnet build，会自动生成SwaggerClient.cs并编译到项目中，同时原来的弃用警告会消失，效果和之前用<OpenApiReference>一致。

内容的提问来源于stack exchange，提问作者Dee J. Doena