Defining a response model

[mat-mcloughlin]

Hey, not sure if this is the best place but hey.

I've managed to get Swashbuckle working with the XML comments however I'm can't figure out how to get it to define a response model for each of the responses.

Is this possible? If so how?

[domaindrivendev]

There is currently some support for adding additional response codes, other than the implied 200/204, via XML comments. See the "Response Codes" section of the readme.

If you go down this route, be sure to include the success (2xx) response code as well as the error ones otherwise it won't show up in the docs.

It's also worth noting, that only the 2xx codes will be accompanied with a schema, which is inferred from the action return type or ResponseTypeAttribute if provided. However, you could very easily create your own "SwaggerResponseAttribute" and a corresponding IOperationFilter (see readme) that inspects all actions for these attributes and creates corresponding Responses on the Operation description:

[SwaggerResponse("201", typeof(Customer))]
[SwaggerResponse("400", typeof(HttpError))]
public IHttpActionResult GetCustomer(int id)

In fact @DavidDeSloovere is currently doing some work for SB that will provide these attributes out of the box but in the meantime you'll have to roll your own :)

[DavidDeSloovere]

I don't know if specifying a response type/model makes sense here.
Strictly speaking, 201 should really return the URL to the new resource.
So I would think that only 200 has a response type, but for that we SB already uses System.Web.Http.Description.ResponseTypeAttribute
Please correct me if you see value in adding the type to SwaggerResponse

[mat-mcloughlin]

But what about 400 bad request.

Is it possible that you have a resource that returns one model for a successful call and a different model for a failed call (a list of errors for example)?

[DavidDeSloovere]

I guess it would be possible. Don't know what the REST police would have to say about that really.
In my API, I return 429 (Too Many Requests) and the information about calls and reset is in the header, not the body.

[DavidDeSloovere]

Turns out you can do it with Web API v2. Don't know about MVC6 or Nancy (@mat-mcloughlin ?).
These are all valid code.

return this.Request.CreateResponse(HttpStatusCode.OK, results);
return this.Request.CreateResponse(HttpStatusCode.Conflict, results);
return this.Request.CreateResponse(HttpStatusCode.Ambiguous, results);
return this.Request.CreateResponse(HttpStatusCode.Gone, results);
return this.Request.CreateResponse(HttpStatusCode.NoContent, results);

[domaindrivendev]

@DavidDeSloovere - I think we should definitely include the flexibility to add specific response types per HttpStatusCode by way of an optional Type property on the SwaggerResponseAttribute.

Rightly so, WebApi and Swagger (with the exception a few constraints) are not overly opinionated on how to build REST/HTTP API's and I want SB to take the same stance.

So much of the rhetoric around REST gets hung up on constraints that can't even be found in the original thesis (https://www.ics.uci.edu/~fielding/pubs/dissertation/top.htm). I've learnt to avoid the mind-numbing debates on "RESTfullness" and just focus my API designs on the set of REST constraints that provide value in a given context - uniform interface, retry-ability & cache-ability through correct use of HTTP verbs, stateless server etc.

[domaindrivendev]

Going to close this and refer back to @DavidDeSloovere's original issue for tracking progress on this- #175

[DavidDeSloovere]

@mat-mcloughlin if you want this code before a release...
You'll need SwaggerResponseAttribute and the AddResponseFromAttributes (IOperationFilter)

https://github.com/DavidDeSloovere/Swashbuckle/blob/68187a2d8b4f00eaa88292998dc6dc4d15043609/Swashbuckle.Core/Annotations/SwaggerResponseAttribute.cs

https://github.com/DavidDeSloovere/Swashbuckle/blob/68187a2d8b4f00eaa88292998dc6dc4d15043609/Swashbuckle.Core/Swagger/Filters/AddResponseFromAttributes.cs

In the config you'll need to add config.OperationFilter<AddResponseFromAttributes>();

Usage:
https://github.com/DavidDeSloovere/Swashbuckle/blob/68187a2d8b4f00eaa88292998dc6dc4d15043609/Swashbuckle.Dummy.Core/Controllers/AttributeAnnotatedController.cs

[hitmanmcc]

I have an issue caused with some of my actions don't return a 200 if they are successful but a 200 is always being listed along with a model schema for the response. If however I use the tag to override that, it will list the proper code but it will no longer display a schema model. How can I keep both? Maintain the correct response and display a schema model?

Thanks.

EDIT: If I use both the tag and the SwaggerResponse attributes, the attributes stop being displayed but the correct code is listed instead of always 200.
For the model schema I first tried annotating an action with a SwaggerOperationFilter with typeof the example schema filter I had defined, the model came up empty.
However, when I dropped the SwaggerResponse attributes and switched all response codes to response xml tags. It correctly displayed the codes for successful responses in the cases where the code was not 200 and it picked up on the model schema I had defined, when I explicitly loaded it in my swaggerconfig class:

c.SchemaFilter<ProductsDefaults>();

[hitmanmcc]

Actually, I just now tested this, it's not exactly working. Since Type appears to be System.Object for all of my entities, for some reason I am unaware of, what I get is the same schema model (the last one loaded) for all of my various entites. This is now what I wanted. Can anybody give me some pointers regarding this? Thanks