Swashbuckle - swagger documentation of returned response?

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;
    }

jps · Answer 1 · 2020-01-16T09:28:40.190

16

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")]

edited Jan 16 '20 at 09:28

answered Jul 25 '17 at 09:45

jps

20,041
15
75
79

3

Unfortunately `SwaggerResponse` is removed in more recent versions of Swashbuckle.AspNetCore. `ProducesResponseType` is the way to go, with optional XML comments if you still want the string explanation (read more about that [here](https://github.com/domaindrivendev/Swashbuckle.AspNetCore/issues/159)). – Jim Aho Jan 16 '20 at 08:59
Thanks @JimAho for the information, I didn't know that. I've updated my answer to let readers know. – jps Jan 16 '20 at 09:14
I just simply solved the status code 200 to 400 while changing the return type from return Ok(json_structure); to return new JsonResult(json_structure); in the exception handler, and the issue is well solved ! . – Mirzan Oct 13 '20 at 06:59

Hezye · Accepted Answer · 2017-07-19T09:51:42.330

11

You can specify the response type with the following attribute:

[ProducesResponseType(typeof(UserCreateResponse), 200)]

edited Jul 19 '17 at 09:51

answered Jul 19 '17 at 07:16

Hezye

1,521
1
13
15

score 1 · Answer 3 · answered Nov 17 '21 at 02:18

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(...) 
{
   ...
}

Swashbuckle - swagger documentation of returned response?

3 Answers3

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

Linked