Swashbuckle / swagger 文档缺失信息答案

【问题标题】：Swashbuckle / swagger Document missing informationSwashbuckle / swagger 文档缺失信息
【发布时间】：2021-02-06 07:43:56
【问题描述】：

我似乎无法理解为什么我的 swagger doc UI 缺少控制器中每个 Gets 和 Posts 的模型架构详细信息？

我正在为 ASP.NET 核心 nuget 包 v4.0.1 运行 SwashBuckle，即使升级到最新包后也没有显示架构详细信息？（我的 WebAPI 是在 Core 2.2 中构建的）

我只浏览了 w.r.t 配置的 swagger 文档，但没有任何东西可以引导我到哪里可以获得要显示的其他信息？

经过一番研究，我发现如果我使用以下属性

[ProducesResponseType(typeof(Models.Customer), StatusCodes.Status200OK)]
[HttpGet("{Id}/customer")]
public async Task<IActionResult> GetCustomer(int Id)

在我想要的招摇 UI 中显示 Schemas 块。但是我不想通过我的每个控制器 Get / Post 方法并添加此属性。没有这个它总是可以工作，但是什么可能阻止它开箱即用？

【问题讨论】：

使用 [ProducesResponseType] 是 Swashbuckle 用于 dotnet 核心、AFAIK 的唯一方法。我还没有看到它以其他方式完成（但我很感兴趣它在过去对你有用吗？）。对于那些感兴趣的人，可以在this related post 中找到完整的 Swashbuckle 示例。
我确实有一个类似的案例。我的返回类型丢失了；放;对于属性。

标签： c# asp.net-core asp.net-core-webapi swagger-ui swashbuckle

【解决方案1】：

Swashbuckle 根据操作的返回类型创建模型。您有多种选择：

您可以返回实际类型（例如public async Task<Models.Customer> GetCustomer(int Id)
如果返回IActionResult，则可以使用ProducesResponseType 属性
您可以返回一个ActionResult<T>，它的工作方式与IActionResult 类似，但使用的是实际类型

您可以查看文档以获取更多信息：https://docs.microsoft.com/en-us/aspnet/core/web-api/action-return-types?view=aspnetcore-3.1

【讨论】：

谢谢@Metoule 解释得很好。我选择了第三个选项，它运行良好:) 但是我觉得ProducesResponseType 可能更适合我，因为在我的方法中我返回一个 Ok 状态，例如Return Ok(<type>) 和 swagger 文档将其翻译为响应成功。

【解决方案2】：

所以，你的方法返回IActionResult，这是很常见的事情，编译器看不到会返回什么真实结果。这就是为什么你应该使用ProducesResponseType。

如果你想使用IActionResult和Asp.Net MVC控制器只能这样使用。

但还有一点是：你真的需要 Asp.Net MVC 控制器吗？如果您需要 Asp.Net MVC 控制器，为什么要创建 swagger 文档？这些东西是矛盾的。

Swagger 需要创建公共 Api 文档。增加外部程序员使用您的 API 的可能性。在这种情况下，最好使用 Api 控制器。

如果您需要使用具有 Autorization 等功能的 Asp.Net MVC 控制器，则无需创建 Swagger，因为它应该在您自己的项目中使用。

【讨论】：