4

Web API 2 (5.0) で Web API ヘルプ ページを使用しています - どちらも最新の Nuget パッケージです。パラメーターであるか、HttpResponseMessage の本文で返されるクラスのプロパティのコメントをヘルプ ドキュメントに表示したいと思います。

たとえば、次のようなコントローラー メソッドがあります。

public HttpResponseMessage Post([FromBody] MyClassType1 myClass)
{
    // Business logic removed for clarity
    return Request.CreateResponse(HttpStatusCode.OK, new MyClassType2());
}

私が持っている XML コメントを上記の投稿アクションのヘルプ ページに表示したいMyClassType1と考えています。MyClassType2

どこを見ても、これはまだサポートされていないようです。しかし、誰かが ApiExplorer を拡張したり、XmlDocumentationProvider に追加したりして、これを機能させることができたのでしょうか?

生成される XML ファイルにコメントとプロパティが含まれていることがわかっているので、それを手動で解析することができます (すべてのパラメーターと戻り値の型はMyAssemblyName.Models名前空間にあるため、その名前空間で始まるメンバー名. ただし、組み込みの Web API ヘルプ ページにはいくつかのキャッシュ機能があることを知っているので、これを既存の機能に組み込むことを好みます (単に追加するだけです)。

Parameters.cshtml テンプレートを次のように更新することで、パラメーターの種類を表示することができました (1 レイヤーのみ)。

@using System.Reflection
@using System.Threading
@using System.Web.Http.Description
@using Regency.API.Services.Areas.HelpPage
@model System.Collections.ObjectModel.Collection<ApiParameterDescription>

<table class="help-page-table">
    <thead>
        <tr><th>Name</th><th>Properties</th><th>Description</th><th>Additional information</th></tr>
    </thead>
    <tbody>
        @foreach (ApiParameterDescription parameter in Model)
        {
            string parameterDocumentation = parameter.Documentation ?? "No documentation available.";
            Type parameterType = parameter.ParameterDescriptor.ParameterType;

            // Don't show CancellationToken because it's a special parameter
            if (!typeof (CancellationToken).IsAssignableFrom(parameter.ParameterDescriptor.ParameterType))
            {
                <tr>
                    <td class="parameter-name"><b>@parameter.Name</b></td>
                    <td class="parameter-properties">
                        @foreach (PropertyInfo property in parameterType.GetProperties())
                        {
                            <text>@property.Name : @property.PropertyType.GetFriendlyTypeName()</text>
                            <br/>
                        }
                    </td>
                    <td class="parameter-documentation"><pre>@parameterDocumentation</pre></td>
                    <td class="parameter-source">
                        @switch(parameter.Source)
                        {
                            case ApiParameterSource.FromBody:
                                <p>Define this parameter in the request <b>body</b>.</p>
                                break;
                            case ApiParameterSource.FromUri:
                                <p>Define this parameter in the request <b>URI</b>.</p>
                                if (parameter.ParameterDescriptor.IsOptional)
                                {
                                    <p>This parameter is <b>optional</b>.</p>
                                }
                                break;
                            default:
                                <p>None.</p>
                                break;
                        }
                    </td>
                </tr>
            }
        }
    </tbody>
</table>

上記のGetFriendlyTypeName()メソッドは、次のように実装されています:リフレクションを使用してジェネリック型の正しいテキスト定義を取得するにはどうすればよいですか?

ただし、これはこれらのクラスからのコメントを取得せず、ネストされた型には役立ちません (たとえば、モデルに複合型のプロパティがある場合、その複合型のプロパティのプロパティは表示されません)。とにかく、型は XML コメントなしでは十分に役に立ちません。

また、これはパラメーターにのみ適用され、HttpResponseMessage の本文に含まれる戻り型には適用されません。ここに示すように実装することで、応答サンプルを機能させることができましResponseTypeAttributeた: Auto generated help pages with return type HttpResponseMessageが、XML コメントを含むプロパティが得られません。リフレクションを使用して、パラメーターの型を再度取得する方法と同様に型を取得できますが、XML コメントを型と一緒にして、入れ子になった複合型を含めたいと思います。

また、サービス呼び出しとは別に、モデル/クラスのドキュメント (型と XML コメントを含むプロパティ) を文書化し、サービス呼び出しに、返される型の名前のみを表示させることも受け入れられると思います (そうすれば、少なくともユーザーは見つけることができます)。そのタイプのドキュメント)。

パラメータまたは戻り値の型のいずれか、できれば両方に対して私がやろうとしていることと同様のことを実装できた人はいますか? または、私を正しい方向に向けるアイデアはありますか?

4

2 に答える 2