Return types, action parameters and data annotations now available in Web API 2.1 Help Page - StrathWeb

Strath

January 21st, 2014

Return types, action parameters and data annotations now available in Web API 2.1 Help Page

On Friday Microsoft released a 2.1 version of Web API (along with MVC 5.1 and Web Pages 3.1). The release announcement was made yesterday and can be read here – but pretty much all of the new features have already been discussed on this blog, when we dissected the 2.1 RC released last month.

One thing I wanted to highlight today though, are the changes to the Help Page, and its new capabilities to document return types, action parameters and data annotations on your models/DTOs.

Getting Web API 2.1

Web API 2.1 is an in place update over the older Nuget packages, which means it’s simply the latest available Web API Nuget package now.

Documenting return types

Web API Help Page will automatically contain information about the return type of your action – as long as your action returns a concrete type rather than HttpResponseMessage or IHttpActionResult.

For example for the following out of the box sample action:

It would look like this:

response_desc

If your action produces HttpResponseMessage or IHttpActionResult instead, you can then use the new ResponseTypeAttribute to hint Web API about the return type.

One more alternative: if you have a documentation provider enabled, you can use the returns XML documentation tag on your action to provide information about the response.

Documenting data annotations

A great new functionality is that Web API Help Page will now generate documentation for data annotations on your DTOs as well. To see this behavior in action, it’s just a matter of adding some annotations to your models. The release also introduces a ModelNameAttribute which you can use to provide a custom name for your models.

Consider the following model and an action:

For this setup, Web API Help page will generate the following output:

data_annotations

Note that the same will be generate for the response type too!

So it uses all the data annotations we had on the model, as well as our custom model names. Out of the box, the following attributes are supported:

  • RequiredAttribute
  • RangeAttribute
  • MaxLengthAttribute
  • MinLengthAttribute
  • StringLengthAttribute
  • DataTypeAttribute
  • RegularExpressionAttribute

You are free to extend the ModelDescriptionGenerator class to provide support for more or for custom ones. Web API Help Page will also respect the following attributes, allowing you to easily exclude specific members from appearing in the Web API Help page:

  • JsonIgnoreAttribute
  • XmlIgnoreAttribute
  • IgnoreDataMemberAttribute
  • NonSerializedAttribute
  • ApiExplorerSettingsAttribute (with IgnoreApi = true)
  • DataContractAttribute (without a single DataMemberAttribute or EnumMemberAttribute)

Documenting action parameters

Finally, Web API Help Page will also now automatically divide the action parameters into those coming from the URI and those coming from the body. For example, for the sample:

We can see that string is required from the body.

parameters

Be Sociable, Share!

  • Pingback: Dew Drop – January 21, 2014 (#1706) | Morning Dew

  • Kedyr

    Thank you for thus write up.

    I am interested in the ResponseType type attribute, how can it be used with complex types. ie an http post that returns HttpResponseMessage which is a complex type

  • André Vianna

    This an excellent post for a so poorly documented feature in .Net.
    I just have one question.
    Do you know where the description of a property comes from? That column is always empty for me.

  • André Vianna

    Excellent post in a topic very poorly documented and also so important.

    I have a question:
    Do you know where to define the body parameter description?
    That column is always empty and I can find the way to set it.
    Thanks

  • Pingback: Web API Help Pages | Software Engineering

  • Scott Vaughan

    Which namespace does [ModelName("")] attribute belong to. I am currently using version Install-Package Microsoft.AspNet.WebApi -Version 5.1.2. Thanks

  • Franklin Peach

    The ResponseType attribute was Exactly what I was looking for. Thanks so much!

  • Md.Ibrahim

    Thanks for this info. There is very little on this topic on the Web.

  • Harry McIntyre

    Is there any way to indicate that you return an empty response?

    • http://www.strathweb.com/ Filip W

      you can do [ResponseType(typeof(void))] but then the help page will simply hide the sample response.

      if you want to print out extra info based on that, you’d have to customize the help page.