web-dev-qa-db-ja.com

swagger-uiページでコントローラーの名前を変更する方法はありますか?

私はSwashbuckleを使用して、WebApiプロジェクトでswaggerとswagger-uiを使用できるようにしています。

次の画像では、swagger-uiページに表示されている2つのコントローラーを確認できます。これらはC#コードにあるとおりに名前が付けられていますが、ここに表示されているものを変更する方法があるかどうか疑問に思いました。

これは主に、ご覧のとおりManagementDashboardWidgetはユーザーフレンドリーな名前ではないため、ユーザーフレンドリーになるように変更したいと思います。

swagger-ui

14
XN16

そのためにタグを使用できます。デフォルトでは、Swashbuckleはすべての操作にコントローラーの名前のタグを追加します。 SwaggerOperationAttributeで上書きできます。たとえば、次の行は、デフォルトのタグValuesをタグTestに置き換えます。

public class ValuesController : ApiController
{
    [SwaggerOperation(Tags = new[] { "Test" })]
    public IHttpActionResult Get()
    {
        // ...
    }
}

これで、GetoperationはグループTestに配置されます。

操作を複数のグループに表示する場合は、タグを追加できます。例えば:

[SwaggerOperation(Tags = new[] { "Test", "Release1" })]

Get操作をグループTestおよびRelease1に配置します。

14
venerik

Venerikの回答を使用してみましたが、指定した新しいタグとともに元のコントローラー名がUIに保持されていました。また、すべての関数に属性を追加する必要があるのも気に入らなかったので、コントローラーに属性を追加するだけでよいソリューションを思いつきました。 2つのステップがあります:

コントローラに DisplayNameAttribute を追加します。

_[DisplayName("Your New Tag")]
public class YourController : ApiController
{
    // ...
}
_

次に、Swagger構成で、GroupActionsBy関数を使用して基本機能をオーバーライドし、その属性で指定した名前をプルできます。

_GlobalConfiguration.Configuration
    .EnableSwagger(c => {

        c.GroupActionsBy(apiDesc => {
            var attr = apiDesc
                .GetControllerAndActionAttributes<DisplayNameAttribute>()
                .FirstOrDefault();

            // use controller name if the attribute isn't specified
            return attr?.DisplayName ?? apiDesc.ControllerName(); 
        });

    })
    .EnableSwaggerUi(c => {
        // your UI config here
    });
_

ControllerName()は、Swagger-Netライブラリで定義されている拡張メソッドです。それを使用していない場合は、_apiDesc.ActionDescriptor.ControllerDescriptor.ControllerName_からコントローラー名を取得することもできます。

3
jtate

コントローラー/クラスレベルでこれを実行したい場合、以下は ここ からの非常に便利な抜粋です。

コントローラで[ApiExplorerSettings(GroupName = "Group")]を使用します

次にスタートアップで

services.AddSwaggerGen(options =>
{
options.SwaggerDoc(version,
    new Info
    {
        Title = name,
        Version = version
    }
);

options.DocInclusionPredicate((_, api) => !string.IsNullOrWhiteSpace(api.GroupName));

options.TagActionsBy(api => api.GroupName);
});

また、注意してください

5.0.0-swashbuckleのベータ版に、タグの配列を返すことをサポートするTagActionsByオーバーロードが含まれるようになりました。これにより、上記のカスタマイズを簡素化できるはずです。

2
restj90

Swashbuckleのバージョン5は、次のオプションをサポートしています(AddSwaggerGen()の呼び出しで使用されます)。

_options.TagActionsBy(api => new[] { api.GroupName });
_

これは、コントローラーまたはアクションで次の属性と組み合わせて使用​​する必要があります。

_[ApiExplorerSettings(GroupName = "...")]
_

ただし、デフォルトでは、グループ名は特定のドキュメントに操作を含めるために使用されます。したがって、これは予期しない結果につながる可能性があります(options.SwaggerDoc(name, ...)の呼び出しでのドキュメントの名前によって異なります)。

それを機能させるには、これを追加する必要があるかもしれません:

_options.DocInclusionPredicate((name, api) => true);
_

ここで、すべての操作について、nameはドキュメントの名前であり、グループ名は_api.GroupName_で使用できます。グループ名に関係なくドキュメントに操作を含めるには、単にtrueを返します。