5

我一直在使用NSwag为我的 WebAPI 生成一个 Angular TS 客户端，我喜欢它。

我终于从 NSwagStudio 转向使用 MSBuild 目标来自动生成我的 json 规范。

我看到有一种生成规范的新方法称为AspNetCoreToSwaggerGenerator，它使用ASP.NET Core API Explorer服务。

文档指定：

此生成器使用ASP.NET Core API Explorer服务生成规范，并将最终取代基于反射的生成器WebApiToSwaggerGenerator。建议将此生成器用于新项目并开始迁移现有项目。

所以我觉得很好，我会用它。然而，我突然收到一些关于缺少路径的错误，原来是来自我的 startup.cs 文件。我觉得这很奇怪，直到我意识到它实际上是在启动我的 Startup 类的一个实例并运行代码——如果它使用 API Explorer 是有道理的。

然而，这让我觉得不仅可能非常危险（如果我在 Startup 中进行了一些奇怪的编码），而且如果它正在运行大量启动代码，也可能会变慢。

我改用这样的旧版本WebApiToSwaggerGenerator：

  <Target Name="NSwag" AfterTargets="Build">
    <Copy SourceFiles="@(Reference)" DestinationFolder="$(OutDir)References" />
    <Exec Command="$(NSwagExe_Core21) webapi2swagger /assembly:$(OutDir)RR.API.DLL /output:rrapi.json" />
    <RemoveDir Directories="$(OutDir)References" />
  </Target>

这会生成一个rrapi.json文件，然后我可以在我的 Angular 构建中运行该文件以实际创建客户端。它似乎非常快并且效果很好。

所以我想知道最佳实践是什么，以及新的AspNetCoreToSwaggerGenerator. 具体来说 ：

  • 如何防止从我的 Startup.cs 文件中运行不必要的代码
  • 实际的好处是什么？这是通过 API Explorer 服务启用更高级的元数据 - 还是 Swagger 3 的一些未来证明？
  • 在典型项目中使用这两种方法的基准是什么。

我基本上想要每次构建 WebAPI 客户端时生成一个静态 .json 文件。我现在看不出有任何理由不使用旧发电机。

更新：这就是我最终使用的（aspnetcore2swagger）。我不记得这里发生的所有事情的确切细节，但这一直运作良好。它创建一个中间 rr.api.json 文件（我在 RR.API 项目中有我所有的 API 东西）。

 <!-- https://github.com/RSuter/NSwag/issues/1159#issuecomment-363886104 -->
 <Target Name="NSwag" AfterTargets="Build">

   <Copy SourceFiles="@(ReferencePath)" DestinationFolder="$(OutDir)References" />
   <Exec Command="$(NSwagExe_Core31) aspnetcore2swagger  /documentName:a /assembly:$(ProjectDir)bin\$(Configuration)\netcoreapp3.1\RR.API.dll /output:$(SpaRoot_APIRoot)rr.api.json" />

   <!-- SAVE https://localhost:5001/swagger/a/swagger.json -->
   <!-- TO http://localhost:54712/src/app/shared/api/rr.api.json -->
   <Exec Command="$(NSwagExe_Core31) run $(SpaRoot_APIRoot)rr.api.nswag /variables:SpaRoot_APIRoot=$(SpaRoot_APIRoot)" />
   <RemoveDir Directories="$(OutDir)References" />

</Target>

我SpaRoot_APIRoot定义为：

<SpaRoot_APIRoot>..\MyAngularProject\src\app\shared\api\</SpaRoot_APIRoot>
4

0 回答 0