Swagger WebApi 在构建时创建 json答案

【问题标题】：Swagger WebApi create json on buildSwagger WebApi 在构建时创建 json
【发布时间】：2020-12-23 08:15:11
【问题描述】：

在我的 web api 的构建任务中，有什么方法可以创建 swagger json？我想使用 json 将其输入代码生成器并生成打字稿定义文件。

非常欢迎任何帮助！

【问题讨论】：

NSwag 为 Web API 控制器生成 Swagger 规范：github.com/NSwag/NSwag
谢谢！有没有办法通过命令行工具一次为所有控制器创建（和组合）json？
您想将多个控制器组合成一个 Swagger 规范吗？（= 或将多个规范合二为一？）
我的 WebAPI 中有多个控制器。我不想为它们中的每一个创建一个 Swagger-Spec 文件。我想进行一个 NSwag 调用并创建一个 Spec 而无需指定 WebAPI 中的控制器（NSwag 应该自动检测它们）
这应该很容易，给我一些时间......我会在它实施后立即关闭以下问题：github.com/NSwag/NSwag/issues/7

标签： asp.net-web-api swagger

【解决方案1】：

我使用的是 Swashbuckle.AspNetCore.Cli（注意：我使用的是 .NET Core 3.1） https://github.com/domaindrivendev/Swashbuckle.AspNetCore

添加以下包：

<PackageReference Include="Swashbuckle.AspNetCore" Version="5.0.0-rc5" />
<PackageReference Include="Swashbuckle.AspNetCore.Newtonsoft" Version="5.3.1" />
<PackageReference Include="Swashbuckle.AspNetCore.Swagger" Version="5.3.1" />

接下来，创建一个工具清单：

dotnet new tool-manifest

安装 Swashbuckle CLI 工具并将其添加到本地清单文件中：

dotnet tool install --version 5.3.1 Swashbuckle.AspNetCore.Cli

现在您可以使用 dotnet 命令生成 swagger.json 文件。例如：

dotnet swagger tofile --output api.json bin/debug/netcoreapp3.1/xxx.yourApi.dll v1

如果您希望在每次构建时生成文件，请在您的 csproj 文件中使用 PostBuild 目标。

<Target Name="PostBuild" AfterTargets="PostBuildEvent">
    <Exec Command="dotnet tool restore" />
    <Exec Command="dotnet swagger tofile --output swagger.json $(OutputPath)\$(AssemblyName).dll v1 " />
</Target>

【讨论】：

我遇到了错误：严重代码描述项目文件行抑制状态错误 NU1202 包 Swashbuckle.AspNetCore.Cli 6.1.3 与 netcoreapp3.1 (.NETCoreApp,Version=v3.1) 不兼容。软件包 Swashbuckle.AspNetCore.Cli 6.1.3 支持： - net5.0 (.NETCoreApp,Version=v5.0) / any - netcoreapp2.1 (.NETCoreApp,Version=v2.1) / any - netcoreapp3.0 (.NETCoreApp ,Version=v3.0) / 任意
这看起来不错，但似乎不支持 dotnet 5.0：It was not possible to find any compatible framework version. The framework 'Microsoft.AspNetCore.App', version '3.0.0' was not found. - The following frameworks were found: 5.0.9
好的！它实际上适用于版本6.1.5

【解决方案2】：

您可以像这样使用NSwag 命令行工具：

nswag.exe webapi2swagger /assembly:"path/to/assembly.dll" /output:"path/to/swagger.json"

这会为给定 DLL 中的所有控制器生成一个 Swagger 规范。

更多信息read this page。

【讨论】：

嗨，Rico，感谢您提供此功能！但是有一个问题：当我想将对象或数组用作 URI 参数时，为什么 NSwag（或 Swagger 本身）会抛出 InvalidOperationException？
这一定是 NSwag 实现中的错误。你能发布一个导致异常的示例 Web API 控制器吗？
你能发布你收到的异常消息吗？
如果我有这样的东西： [HttpPut] [Route("xyz/{data}")] public string Xyz(MyClass data) { return "abc";我得到一个 System.InvalidOperationException：参数“数据”不能是对象或数据。您似乎积极否认数据参数。澄清一下：我为 MyClass 创建了一个 ModelBinder，因此可以从字符串中解析它，反之亦然。
好的，但这是调用服务时的实际运行时错误，而不是 NSwag 工具的异常？