Swashbuckle / swagger 文檔缺失信息

Question

我似乎無法理解為什么我的 swagger doc UI 缺少​​控制器中每個 Gets 和 Posts 的模型架構詳細信息？

我正在為 ASP.NET 核心 nuget 包 v4.0.1 運行SwashBuckle ，即使升級到最新包后也沒有顯示架構詳細信息？ （我的 WebAPI 是在 Core 2.2 中構建的）

我只瀏覽了 swagger 文檔，但沒有任何內容可以指導我在哪里可以獲取要顯示的附加信息？

經過一番研究，我發現如果我使用以下屬性

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

在 swagger UI 中顯示Schemas塊，這正是我想要的。 但是，我不想遍歷我的每個 Controller Get / Post 方法並添加此屬性。 它總是在沒有這個的情況下工作，但是什么可以阻止它開箱即用？

Answer 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

Answer 2

因此，您的方法返回IActionResult ，這是很常見的事情，編譯器看不到將返回什么實際結果。 這就是您應該使用ProducesResponseType的原因。

如果您想使用IActionResult和 Asp.Net MVC 控制器，則只能以這種方式使用。

但另一點是：你真的需要 Asp.Net MVC 控制器嗎？ 如果您需要 Asp.Net MVC 控制器，為什么要創建 swagger 文檔？ 這些事情是矛盾的。

Swagger 需要創建公共 Api 文檔。 添加外部程序員使用您的 API 的可能性。 在這種情況下，最好使用 Api 控制器。

如果您需要使用具有 Autorization 等功能的 Asp.Net MVC 控制器，那么您不需要創建 Swagger，因為它應該在您自己的項目中使用。