revelio

Enterprise Web API Documentation

Enhancing Your Documentation

The Revelio.Extend NuGet package provides attributes that cover common documentation needs. These attributes add information to the three main objects in Revelio:

  • Endpoint: In Web API, this is analogous a public method on an ApiController.
  • Parameter: Data passed to an endpoint. This could be from the query string, the HTTP request body, or a value in the URL.
  • Property: Data contained in an object in the request or response.

To install this package, run the following command from the Package Manager Console:

PM> Install-Package Revelio.Extend

Most attributes can also be used with XML documentation, which does not require the NuGet package. However, you will need to verify that your build is set up to generate documentation. In your project properties, select the Build tab and check the "XML documentation file" checkbox. Verify that the file name is the same as the assembly name (e.g. Contoso.Web.API.dll and Contoso.Web.API.XML).

Common Attributes

The following attributes are applicable to endpoints, parameters, and properties.

DescriptionAttribute

When a name isn't enough, a description can help your users understand the purpose.
[Description("Returns the address for the given addressId")]
public Address GetAddress(int addressId)
/// <summary>
/// Returns the address for the given addressId
/// </summary>
public Address GetAddress(int addressId)

ExcludeFromDocumentationAttribute

If there's something you'd rather not have shown in the documentation, you can explicitly exclude it with this attribute.
[ExcludeFromDocumentation]
public Guid InternalId { get; set; }
/// <exclude>true</exclude>
public Guid InternalId { get; set; }
/// <exclude>true</exclude>
public HttpResponseMessage InternalEndpoint()
/// <param name="userId" exclude="true">User Id</param>
public HttpResponseMessage GetUser(int userId)

Endpoints

These attributes are used on controller methods to provide endpoint-level information.

IdAttribute

Provides a unique ID for the given endpoint. This allows you to track an endpoint across any number of changes. If no ID is provided, one will be generated based on endpoint attributes (route, method, and parameters)
[Id("getAddress")]
public Address GetAddress(int addressId)
/// <id>getAddress</id>
public Address GetAddress(int addressId)

GroupAttribute

This attribute allows you to display your endpoints together in a high-level group. An endpoint can only belong to one group.
[Group("User Profile")]
public Address GetAddress(int addressId)
/// <group>User Profile</group>
public Address GetAddress(int addressId)

ResponseAttribute

RESTful services often return different response codes and contents for error scenarios. This attribute allows you to easily convey this information.
[Response(HttpResponseCode.OK, "Address information", typeof(Address))]
[Response(HttpResponseCode.NotFound, "Address with the given id does not exist", typeof(string))]
[Response(HttpResponseCode.Forbidden, "User does not have access to this address", typeof(string))]
public Address GetAddress(int addressId)

CustomRouteAttribute

If you don't use System.Web.Http.RouteAttribute for routing, you can override the default [controller_name]/[action_name] behavior with this attribute.
[CustomRoute("address/{addressId}")]
public Address GetAddress(int addressId)
/// <route>address/{addressId}</route>
public Address GetAddress(int addressId)

Parameters

The following attributes are used on controller method parameters and properties for request and response types.

IsOptionalAttribute

Marks the parameter as not being required.
public List<Person> ListPersons([IsOptional]string startsWith = null)
/// <param name="startsWith" optional="true">Start of first or last name</param>
public List<Person> ListPersons(string startsWith = null)

ExampleAttribute

Provides some sample values for the parameter.
public List<Address> FindAddresses(
    [Example("Pennsylvania Ave", "221B Baker Street")]string toMatch)
/// <param name="toMatch">String to match</param>
/// <examples name="toMatch">
///     <example>Pennsylvania Ave</example>
///     <example>221B Baker Street</example>
/// </examples>
public List<Address> FindAddresses(string toMatch)

DocumentAsAttribute

Displays the parameter type as a different type. This is helpful if you have custom model binding
//Our custom model binder accepts a comma-separated list of ints translates it into a List<int>
public List<Address> ListAddresses([DocumentAs(typeof(string))]List<int> commaSeparatedIds)
{
    //snip
}

Properties

The following attributes are used on properties for request and response types.

IsOptionalAttribute

Marks the property as not being required.
public class Person
{
    public string FirstName { get; set; }
    public string LastName { get; set; }
    [IsOptional]
    public string NickName { get; set; }
}
public class Person
{
    public string FirstName { get; set; }
    public string LastName { get; set; }
    /// <optional>true</optional>
    public string NickName { get; set; }
}

ExampleAttribute

Provides some sample values for the property.
public class Address
{
    public string AddressLine1 { get; set; }
    [Example("Suite 123", "Unit 42")]
    public string AddressLine2 { get; set; }
    public string City { get; set; }
    [Example("FL", "NY", "IA")]
    public string State { get; set; }
}
public class Address
{
    public string AddressLine1 { get; set; }
    /// <examples>
    ///     <example>Suite 123</example>
    ///     <example>Unit 42</example>
    /// </examples>
    public string AddressLine2 { get; set; }
    public string City { get; set; }
    /// <examples>
    ///     <example>FL</example>
    ///     <example>NY</example>
    ///     <example>IA</example>
    /// </examples>
    public string State { get; set; }
}

DocumentAsAttribute

Displays the property type as a different type. This is helpful if you have custom model binding
public class CreatePersonRequest
{
    //Our custom model binder accepts an array of strings and translates it into a NicknameCollection
    [DocumentAs(typeof(List<string>))]
    public NicknameCollection Nicknames { get; set; }
}