1

Web API ヘルプ ページを使用していますが、他のメソッドへのリンクを含めたいと考えています。XML ドキュメント タグは Web API 2 ヘルプ ページで処理されませんか? <see cref='...'> の使用はサポートされていません。

ドキュメントに独自の <a href='...'> リンクを記述し、Web Api ヘルプ ページで説明されている方法を使用するよりも優れたオプションはありますか?これらの <a> タグを取得するには、xml ドキュメントで html をエスケープしないでください。ヘルプに出力しますか? 将来の変化に対して非常に脆いようです。

私が考えることができる唯一の代替手段は、API エクスプローラーを強制的に 2 回実行することです。1 回目はすべての異なるルートとそれに対応するヘルプ ページの URL をキャッシュし、2 回目は実際にドキュメントを生成します。しかし、これをどこに接続すればよいかわかりません (または、それが可能かどうかもわかりません)。

4

1 に答える 1

4

リンクを正しく変換するものを書くことができました。

概要は次のとおりです。

Help Controller のコンストラクターで、cref で見つかった文字列 (M:Api.Method.Description(System.String) など) と関連する ApiDescription の間の新しい Lazy IDictionary マッピングを作成します。

        _methodReferences = new Lazy<IDictionary<string, ApiDescription>>(() => {
            var dictionary = new Dictionary<string, ApiDescription>();

            var apiExplorer = new ApiExplorer(config);

            foreach (var apiDescription in apiExplorer.ApiDescriptions)
            {
                var descriptor = apiDescription.ActionDescriptor as ReflectedHttpActionDescriptor;
                if (descriptor != null)
                {
                    var methodName = string.Format(
                        @"M:{0}.{1}({2})",
                        descriptor.MethodInfo.DeclaringType.FullName,
                        descriptor.MethodInfo.Name,
                        string.Join(@",",descriptor.GetParameters().Select(x => x.ParameterType.FullName))
                        );
                    dictionary[methodName] = apiDescription;
                }

            }
            return dictionary;
        });

この遅延を、ページをサポートするさまざまなモデルに渡します (追加のモデルを作成する必要がある場合があります)。次のコードを使用して、すべての基本クラスを指定しました。

public abstract class HelpPageModelBase
{
    private static Regex _seeRegex = new Regex("<see cref=\"([^\"]+)\" />");
    private readonly Lazy<IDictionary<string, ApiDescription>> _methodReferences;

    protected HelpPageModelBase(Lazy<IDictionary<string, ApiDescription>> methodReferences)
    {
        _methodReferences = methodReferences;
    }

    protected HelpPageModelBase(HelpPageModelBase parent)
    {
        _methodReferences = parent._methodReferences;
    }

    public string ParseDoc(string documentation, UrlHelper url)
    {
        if (documentation == null)
        {
            return null;
        }
        return _seeRegex.Replace(documentation,
                                 match => {
                                     if (_methodReferences.Value.ContainsKey(match.Groups[1].Value))
                                     {
                                         var descriptor = _methodReferences.Value[match.Groups[1].Value];

                                         return string.Format(@"<a href='{0}'>{1} {2}</a>",
                                                              url.Action("Api",
                                                                         "Help",
                                                                         new {
                                                                             apiId = descriptor.GetFriendlyId()

                                                                         }),
                                                              descriptor.HttpMethod.Method,
                                                              descriptor.RelativePath
                                             );
                                     }
                                     return "";
                                 });
    }
}

持っていたビューのどこでも、api.Documentation.Trim() または既にWeb Api ヘルプ ページHtml.Raw(api.Documentation)に従っている場合は、xml ドキュメントで html をエスケープしないでください。

@Html.Raw(Model.ParseDoc(api.Documentation, Url))

これを行うには、さまざまな ModelDescriptions を HelpPageModelBase から継承し、親 API モデル (または簡単な場合は Lazy) を渡す必要があることがわかりますが、最終的には機能します。

このソリューションには特に満足していません。デフォルトの Http 構成を使用して Lazy を生成する何らかの形式の静的 ParseDoc メソッドを使用する方が簡単な場合があります (ただし、作成した他の拡張機能が原因で、私の場合は機能しません)。より良い方法を見つけたら、共有してください！うまくいけば、それがあなたの出発点になります。

于 2014-10-08T11:19:45.270 に答える