Documentar descripciones en tipos complejos.

Question

Dentro de mi API, estoy tratando de documentar las diferentes descripciones de los campos, sin embargo, ninguno de los atributos parece funcionar. Sé que se supone que esta funcionalidad se ha implementado recientemente dentro de WEBAPI 5.1 (ejecutando WEBAPI.HELPPAGE 5.1.2).

Páginas de ayuda de ASP.NET WEB API: Anotaciones de datos del modelo de documento - Artículo 877

Estoy tratando de documentar tanto mi modelo de respuesta:

y los campos / propiedades individuales

He intentado una mezcla de comentarios XML, datamember y exhibir atributos, pero ninguno parece ser recogido.

/// <summary>
/// blah blah blah
/// </summary>
[DataContract(Name = "Application")]
public class Application
{
    /// <summary>
    /// Please Display!
    /// </summary>
    [DataMember(Order = 0)]
    [Display(Description="Please Display!")]
    [StringLength(11, MinimumLength = 11)]
    public string ApplicationId { get; set; }

Aquí hay una muestra de mis áreas / help / app_start / helppageconfig.cs

namespace WebAPI.Areas.HelpPage
{
    #pragma warning disable 1591
    /// <summary>
    /// Use this class to customize the Help Page.
    /// For example you can set a custom <see cref="System.Web.Http.Description.IDocumentationProvider"/> to supply the documentation
    /// or you can provide the samples for the requests/responses.
    /// </summary>
    public static class HelpPageConfig
    {
        public static void Register(HttpConfiguration config)
        {
            // remove unwanted formatters
            config.Formatters.Clear();
            var jsonsettings = new JsonSerializerSettings() { DateParseHandling = DateParseHandling.None };
            config.Formatters.Add(new JsonMediaTypeFormatter());
            config.Formatters.Add(new XmlMediaTypeFormatter());
            config.SetDocumentationProvider(new XmlDocumentationProvider(HttpContext.Current.Server.MapPath("~/bin/WebAPI.XML")));
            // create sample objects
            config.SetSampleObjects(new Dictionary<Type, object>
            {
                { typeof(MyResponse), new MyResponse() { 
                    Message = "Key d795677d-6477-494f-80c5-874b318cc020 is not recognised", 
                    Code = ResponseCode.InvalidKey, Id = null }
                }
            });             
            //*** More Sample Requests ***
        }
    }
    #pragma warning restore 1591
}

update 10/06/2014 : Mis definiciones de clase se almacenan en una biblioteca separada. He notado una discrepancia aquí. La biblioteca principal de la API y la definición de clase generaban archivos XML separados.

proyecto API

Proyecto de definición

He intentado rectificar esto haciendo que la definición escriba al mismo proyecto XML. Sin embargo, esto no funciona, y las entradas de definición de clase no se agregan.

Answer 1

Para tener un contenido que se muestra en la sección Descripción, debe sentir la sección de comentarios XML.Si desea que su clase de modelo se coloque dentro de su proyecto WEBAPI, esto sería una solución.Su problema es que necesita leer la documentación XML Formulario 2 archivos XML y una vez y XMlDocumentationProvider no admite eso.Mi sugerencia es crear su propio FilsoFilesXMlDocumentationProvider con un poco de esfuerzo así:

public class MultipleFilesXmlDocumentationProvider : IDocumentationProvider
{
    IEnumerable<XmlDocumentationProvider> xmlDocumentationProviders;

    public MultipleFilesXmlDocumentationProvider(IEnumerable<string> documentPaths)
    {
        xmlDocumentationProviders = documentPaths.Select(path => new XmlDocumentationProvider(path));
    }

    public string GetDocumentation(HttpParameterDescriptor parameterDescriptor)
    {
        foreach(XmlDocumentationProvider provider in xmlDocumentationProviders)
        {
            string documentation = provider.GetDocumentation(parameterDescriptor);
            if(documentation != null)
                return documentation;
        }
        return null;
    }

    public string GetDocumentation(HttpActionDescriptor actionDescriptor)
    {
        foreach (XmlDocumentationProvider provider in xmlDocumentationProviders)
        {
            string documentation = provider.GetDocumentation(actionDescriptor);
            if (documentation != null)
                return documentation;
        }
        return null;
    }

    public string GetDocumentation(HttpControllerDescriptor controllerDescriptor)
    {
        foreach (XmlDocumentationProvider provider in xmlDocumentationProviders)
        {
            string documentation = provider.GetDocumentation(controllerDescriptor);
            if (documentation != null)
                return documentation;
        }
        return null;
    }

    public string GetResponseDocumentation(HttpActionDescriptor actionDescriptor)
    {
        foreach (XmlDocumentationProvider provider in xmlDocumentationProviders)
        {
            string documentation = provider.GetDocumentation(actionDescriptor);
            if (documentation != null)
                return documentation;
        }
        return null;
    }
}

Esto será solo envoltorio sobre XmlDocumentationProvider: funcionará con una colección de XmlDocumentationProvider y busca el primero que proporcionará la documentación deseada.Luego cambia su configuración en HelpPageconfig para usar su FileFilesXMlDocumentationProvider:

config.SetDocumentationProvider(
    new MultipleFilesXmlDocumentationProvider(
        new string[] { 
            HttpContext.Current.Server.MapPath("~/bin/WebAPI.XML"), 
            HttpContext.Current.Server.MapPath("~/bin/EntityModel.Definitions.XML")
        }
    )
 );

Por supuesto, tenga en cuenta que para la configuración por encima de ambos archivos XML debe estar dentro de la carpeta de Bin de WBAPI.