使用Swagger的特定狀態代碼的響應模型

Question

我使用Swagger來記錄我的REST API（使用asp.net web api 2）。 對於給定的api調用，是否有一種方法可以為每個可能的響應提供響應模型？ 我正在使用xml注釋來注釋狀態代碼響應，如下所示：

    /// <summary>
    /// Save a person
    /// </summary>
    /// <response code="200">Ok</response>
    /// <response code="400">Bad Request</response>
    /// <response code="500">Internal Server error</response>
    public HttpResponseMessage SavePerson() {...}

Answer 1

您可以嘗試在XML評論中使用cref =“TYPE HERE”。

/// <response code="400" cref="CustomErrorModel">Bad Request</response>

我會建議使用Swagger給你的注釋。

[SwaggerResponse(HttpStatusCode.OK, Type = typeof(OnlineMerchantQueryResponseInformation))]

使用此屬性控制您的控制器。

Answer 2

您的簽名表示您正在返回HttpResponseMessage，而不是數據模型。 如果您正在返回IActionResult，並且您正在使用ASP.NET Core，則可以使用“ProducesResponseType”屬性：

[ProducesResponseType(typeof(IEnumerable<YourModel>), 200)]

ProducesResponsesType位於Microsoft.AspNetCore.Mvc名稱空間中。

請參閱https://github.com/domaindrivendev/Swashbuckle.AspNetCore#list-operation-responses “明確的回應”

Answer 3

如果您使用Swashbuckle，您可以嘗試

 [SwaggerResponse(200, typeof(CustomModel))]

並且您還要為該響應類型添加注釋作為可選的第三個參數

[SwaggerResponse(200, typeof(CustomModel), "returns a new id of the bla bla")]

注意：該屬性位於名稱空間Swashbuckle.AspNetCore.Annotations中