StatusCode Metadata

[chadboyer]

Will there be a way to add metadata to my API actions depicting the different status codes it returns?

For example:

[ResposeType( HttpStatusCode.OK, typeof(Customer) ]
[ResponseType( HttpStatusCode.BadRequest, typeof(ValidationException)]

I believe this will be useful for the various tooling ( Swagger Generators and Help Doc Generators ) to understand the types of HTTP status codes your Web API can return.

[danroth27]

Swashbuckle defines it's own response attributes for specifying the additional metadata needed for Swagger generation.

@rynowak Should we have built-in attributes for capturing this metadata and make the metadata available via ApiExplorer?

[chadboyer]

Yes, status codes should be available via the ApiExplorer too. Right now, each vender is creating their own custom attribute to get around this limitation.

Almost all tooling around Web APIs needs to know about the status codes. - help docs, swagger, ect.

[chadboyer]

Knowing the status codes is every bit as important as knowing the response type.

[danroth27]

@domaindrivendev FYI

[domaindrivendev]

Awesome!

[chadboyer]

+1 - Awesome!

[rynowak]

Some design notes on this:

Example

[Produces("application/json, Type = typeof(Widget)]
[ProducesResponseTypeAttribute(typeof(Errors), StatusCodes.BadRequest)]
public IActionResult DoThing() { }

Update IApiResponseMetadataProvider

public class IApiResponseMetadataProvider
{
    int StatusCode { get; set; }
}

Update ProducesAttribute and set StatusCode to 200 by default

Add ProducesResponseTypeAttribute (allow multiple)

[AttributeUsage(AttributeTargets.Class | AttributeTargets.Method, AllowMultiple = true, Inherited = true)]
public class ProducesResponseTypeAttribute : Attribute, IFilterMetadata, IApiResponseMetadataProvider
{
    public ProducesResponseTypeAttribute(Type type, int statusCode)
    public int StatusCode { get; }
    public Type Type { get; }
}

Move ApiDescription.ResponseModelMetadata and ApiDescription.ResponseType to ApiResponseFormat. Add StatusCode to ApiResponseFormat

Update the DefaultApiDescriptionProvider to take the cross product of "content-type" X "tuple(status code, type)" and run it through conneg.

[rynowak]

@kichalla - added some design notes

@domaindrivendev - any concerns with this?

[danroth27]

Should the ProducesAttribute still have a Type property if we are going to introduce a ProducesResponseTypeAttribute?

[kichalla]

👍 on what @danroth27 mentioned.

[rynowak]

I think it's nicer to have as a shorthand for when you only want to specify one + you're already specifying a content type.

[khellang]

One thing; would you flip the order of the int and Type parameters?

I think it makes more sense to specify which status code produces which model, instead of the other way around:

[ProducesResponseTypeAttribute(200, typeof(Customer))]
[ProducesResponseTypeAttribute(500, typeof(GenericError))]
[ProducesResponseTypeAttribute(422, typeof(ValidationError))]
public IActionResult DoThing() { }

[kichalla]

I like @khellang's suggestion here. One of the scenarios I am encountering where this makes more sense is with overriding. Example:

[ProducesResponseType(500, typeof(GenericError))]
public class TestController
{
      [Produces("text/json", "application/json", typeof(ProductDetails))]
      [ProducesResponseType(500, typeof(MoreSpecificErrorForThisAction))]
      public IActionResult Details()
      {
              ....
      }
}

So for the Details action and for the 500 status code, the more specific error is used and for the rest of the actions, the one on the controller is used.

@rynowak thoughts?

[rynowak]

The overriding part just falls out of the nature of being a filter.

re: the ordering of parameters, let's come up with a name that we like and let that dictate what order we use. ProducesResponseType was just a strawman to start work 😆