ASP.Net Web API Help Pages: Document Model Data Annotations

Topics: ASP.NET Web API
Feb 28, 2013 at 10:52 AM
Hello,

Does anyone know of a way to have the ApiExplorer generate documentation which details the Properties (and their data annotations) of an ApiController action paramater?

For example:

I have an ApiController with action method:
public HttpResponseMessage PostResource(Resource resource)
The Resource object is:
    [DataContract(Namespace = "")]
    public class Resource
    {
        [DataMember]
        public long Id { get; set; }

        /// <summary>
        /// Determines whether this Resource should be made available to the public.
        /// </summary>
        [DataMember(IsRequired = true)]
        [Required]
        public bool IsPublic { get; set; }

        /// <summary>
        /// Represents the various fields which make up the composite surrogate key of this Resource.
        /// </summary>
        [DataMember(IsRequired = true)]
        [Required]
        public ResourceKey ResourceKey { get; set; }

    }
And then the ResourceKey object is:
    public class ResourceKey
    {
        /// <summary>
        /// Identifies the System which created the Resource.
        /// </summary>
        [StringLength(50, MinimumLength = 1)]
        [Required]
        public string SystemId { get; set; }

        /// <summary>
        /// The value of the ID which identifies the Resource within the contributing system.
        /// </summary>
        [StringLength(50, MinimumLength = 1)]
        [Required]
        public string SystemDataId { get; set; }

        /// <summary>
        /// Represents the type of Id which is used within the contributing system to identify the Resource.
        /// </summary>
        [StringLength(50, MinimumLength = 1)]
        [Required]
        public string SystemDataIdType { get; set; }

        /// <summary>
        /// Identities the type of entity that the Resource represents.
        /// </summary>
        [StringLength(50, MinimumLength = 1)]
        [Required]
        public string SystemEntityType { get; set; }
    }
Consumers of the API should be made aware what the "IsPublic" field is for because it has important implications.

Consumers of the API also need to know what restrictions apply to the data they send in.

e.g That the ResourceKey.SystemId must be present, must be a string and must be between 1 and 50 characters.

How can we incorporate this information into the Web API Help Pages???
Developer
Feb 28, 2013 at 4:20 PM
Hi,

Currently we do not have out of the box support for generating help based on data annotations. But we have seen many users asking for it. Could you please file an request for it in the issue tracker?

Workaround:
Help page depends on ApiExplorer to get details of controllers and actions and actions' parameters. You could access the parameter related information via the ApiParameterDescription type. Following are some locations which might be interesting to consider:
  1. GenerateApiModel method in Areas\HelpPage\HelpPageConfigurationExtensions.cs.
  2. \Areas\HelpPage\Views\Help\DisplayTemplates_Parameters.cshtml_
Thanks,
Kiran
Mar 1, 2013 at 1:55 PM
Hi Kiran,

Thanks for the reply.

Just to make sure I put the request in the right place...can you please confirm that this is the correct forum:

http://aspnet.uservoice.com/forums/147201-asp-net-web-api

Thanks!
Developer
Mar 1, 2013 at 2:50 PM
Hi,

Issue tracker is located here: http://aspnetwebstack.codeplex.com/workitem/list/basic

I tried to look in the 'uservoice' to see if i can move your request from there to the issue tracker, but somehow i unable to find it.

Thanks,
Kiran