记录复杂类型的描述

在我的API中，我试图记录不同的字段描述，但是没有任何属性看起来可行。 我知道这个功能应该是最近在WebAPI 5.1中运行的（运行WebAPI.HelpPage 5.1.2）。

ASP.Net Web API帮助页面：文档模型数据注释 - 工作项目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; }

以下是我的Areas / 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项目

定义项目

我试图通过将定义写入同一个XML项目来解决这个问题。 但是这不起作用，并且不添加类定义条目。

---

要在Description部分显示内容，您需要感受XML注释的部分。 如果你的模型类放在你的webapi项目中 - 那么这将是一个解决方案。 你的问题是，你需要阅读xml文档形式2 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文件都应该位于WebAPI项目的bin文件夹中。

链接地址: http://www.djcxy.com/p/79451.html

上一篇: Documenting descriptions on Complex Types

下一篇: Hosting Open Source code with a restrictive license on GitHub