Модель ответа для определенных кодов состояния с использованием Swagger

Я использую Swagger для документирования моего REST API (с использованием asp.net web api 2). Есть ли способ в swagger дать модели ответов для каждой возможной реакции для данного вызова 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() {...}

enter image description here

ОТВЕТЫ

Ответ 1

Вы можете попробовать использовать cref = "TYPE HERE" в ваших комментариях XML, как это.

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

В ut Я бы предложил использовать аннотации, которые дает вам Swagger.

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

свяжите свои контроллеры с этим.

Ответ 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 "Явные ответы"

Ответ 3

Если вы используете Swashbuckle, вы можете попробовать

 [SwaggerResponse(200, typeof(CustomModel))]

и вы дополнительно добавляете комментарий для этого типа ответа в качестве необязательного третьего параметра

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

Примечание. Атрибут находится в пространстве имен Swashbuckle.AspNetCore.Annotations