c# - 複合型に関する説明の文書化

Question

私の 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
}

2014 年 10 月 6 日更新: 私のクラス定義は別のライブラリに保存されます。ここで矛盾に気づきました。メイン API とクラス定義ライブラリは、別々の XML ファイルを生成していました。

API プロジェクト

定義プロジェクト

定義を同じ XML プロジェクトに書き込むことで、これを修正しようとしました。ただし、これは機能せず、クラス定義エントリは追加されません。

Answer 1

説明セクションにコンテンツを表示するには、XML コメントのフィール セクションが必要です。モデル クラスを webapi プロジェクト内に配置する場合、これが解決策になります。あなたの問題は、2つのxmlファイルからxmlドキュメントを1回読む必要があり、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 のコレクションで動作し、必要なドキュメントを提供する最初のものを探します。次に、MultipleFilesXmlDocumentationProvider を使用するように HelpPageConfig の構成を変更します。

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

もちろん、上記の構成では、両方の XML ファイルが WebAPI プロジェクトの bin フォルダー内にある必要があることを考慮してください。