Swashbuckle - 返回响应的大摇大摆的文档？

Question

Swashbuckle would not generate swagger.json with an output of "UserCreateResponse", how do you fix this?

    [HttpPost]
    public async Task<IActionResult> Update([FromBody]UserCreate Request)
    {
        UserCreateResponse response = new UserCreateResponse();

        //do something here

        // returns UserCreateResponse with http status code 200
        return Ok(response);
    }

You can't do this, because its not going to return the http status code, 200,400,401 etc

    [HttpPost]
    public async Task<UserCreateResponse> Update([FromBody]UserCreate Request)
    {
        UserCreateResponse response = new UserCreateResponse();

        //do something here

        // returns UserCreateResponse
        return response;
    }

Answer 1

The below solution works only for Swashbuckle versions prior to V6.0!

From V6.0 onwards SwaggerResponse isn't supported anymore, see here .

---

Another variant is the use of the SwaggerResponse attribute, which also allows to provide an additional description:

[SwaggerResponse(HttpStatusCode.OK, "UserDTO", typeof(UserDTO))]
public async Task<IHttpActionResult> Get([FromODataUri] int key)
{
    var result = await UserRepo.GetAsync(key);
    ...
    return Ok(result);
}

which produces output as shown here:

It's also possible to omit the type to document other status codes which do not return an entity:

[SwaggerResponse(HttpStatusCode.NotFound, "no data found")]
[SwaggerResponse(HttpStatusCode.BadRequest, "requiered request headers not found")]

Answer 2

您可以使用以下属性指定响应类型：

[ProducesResponseType(typeof(UserCreateResponse), 200)]

Answer 3

Starting from .NET Core 2.1, using ActionResult<T> would be the recommended approach to specify the returned type. It gets picked by Swashbuckle and also adds type checks at the compilation.

You also can add description on the response via XML comment ( docs ).

So for the OP's example it would be

/// <summary> 
///     Update the user 
/// </summary>
/// <response code="200"> User's data </response>
[HttpPost]
[ProducesResponseType(StatusCodes.Status200OK)]
public async Task<ActionResult<UserCreateResponse>> Update(...) 
{
   ...
}