Документирование описаний сложных типов

Question

В моем API я пытаюсь задокументировать описания различных полей, однако ни один из атрибутов не работает. Я знаю, что эта функциональность, как предполагается, была недавно реализована в WebAPI 5.1 (работает WebAPI.HelpPage 5.1.2).

Страницы справки веб-API ASP.Net: аннотации данных модели документа - рабочий элемент 877

Я пытаюсь документировать мою модель ответа:

И отдельные поля / свойства

Я пробовал смесь XML-комментариев, атрибутов DataMember и Display, но ни один из них не был подобран.

/// <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; }

Вот пример из моего Области /HelpPage/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
}

Обновление 10/06/2014: определения моего класса хранятся в отдельной библиотеке. Я заметил несоответствие здесь. Основной API и библиотека определений классов генерировали отдельные XML-файлы.

API Project

Определение проекта

Я попытался исправить это, записав Определение в тот же проект XML. Однако это не работает, и записи определения класса не добавляются.

Answer 1

Чтобы содержимое отображалось в разделе "Описание", вам необходимо ознакомиться с разделом комментариев XML. Если вы хотите, чтобы ваш класс модели был помещен в ваш проект webapi - тогда это было бы решением. Ваша проблема заключается в том, что вам нужно прочитать документацию xml из двух файлов xml и один раз, и XmlDocumentationProvider не поддерживает это. Я предлагаю создать свой собственный MultipleFilesXmlDocumentationProvider с небольшим усилием, подобным этому:

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;
    }
}

Это будет просто обертка над XmlDocumentationProvider - она ​​будет работать с коллекцией XmlDocumentationProvider и ищет первую, которая предоставит необходимую документацию. Затем вы изменяете свою конфигурацию в HelpPageConfig, чтобы использовать ваш MultipleFilesXmlDocumentationProvider:

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

Конечно, примите во внимание, что для приведенной выше конфигурации оба XML-файла должны находиться в папке bin проекта WebAPI.