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.
Install-Package Microsoft.AspNet.WebApi
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:
public string Get(int id)
{
return "value";
}
It would look like this:
If your action produces HttpResponseMessage or IHttpActionResult instead, you can then use the new ResponseTypeAttribute to hint Web API about the return type.
[ResponseType(typeof(string))]
public HttpResponseMessage Get(int id)
{
return new HttpResponseMessage(HttpStatusCode.OK)
{
Content = new StringContent("hello")
};
}
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:
[ModelName("DTO")]
public class MyDto
{
[Required]
public string Id { get; set; }
[RegularExpression("[a-z]")]
public string Text { get; set; }
[MaxLength(10)]
public double[] Values { get; set; }
public ChildDto Child { get; set; }
}
[ModelName("Child")]
public class ChildDto
{
public string Name { get; set; }
}
//action
public void Post(MyDto dto)
{}
For this setup, Web API Help page will generate the following output:
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:
public void Post([FromBody]string value)
{}
We can see that string is required from the body.
