私はSwashbuckleを使用して、WebApiプロジェクトでswaggerとswagger-uiを使用できるようにしています。
次の画像では、swagger-uiページに表示されている2つのコントローラーを確認できます。これらはC#コードにあるとおりに名前が付けられていますが、ここに表示されているものを変更する方法があるかどうか疑問に思いました。
これは主に、ご覧のとおりManagementDashboardWidget
はユーザーフレンドリーな名前ではないため、ユーザーフレンドリーになるように変更したいと思います。
そのためにタグを使用できます。デフォルトでは、Swashbuckleはすべての操作にコントローラーの名前のタグを追加します。 SwaggerOperationAttribute
で上書きできます。たとえば、次の行は、デフォルトのタグValuesをタグTestに置き換えます。
public class ValuesController : ApiController
{
[SwaggerOperation(Tags = new[] { "Test" })]
public IHttpActionResult Get()
{
// ...
}
}
これで、Get
operationはグループTest
に配置されます。
操作を複数のグループに表示する場合は、タグを追加できます。例えば:
[SwaggerOperation(Tags = new[] { "Test", "Release1" })]
Get
操作をグループTest
およびRelease1
に配置します。
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
_からコントローラー名を取得することもできます。
コントローラー/クラスレベルでこれを実行したい場合、以下は ここ からの非常に便利な抜粋です。
コントローラで[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オーバーロードが含まれるようになりました。これにより、上記のカスタマイズを簡素化できるはずです。
Swashbuckleのバージョン5は、次のオプションをサポートしています(AddSwaggerGen()
の呼び出しで使用されます)。
_options.TagActionsBy(api => new[] { api.GroupName });
_
これは、コントローラーまたはアクションで次の属性と組み合わせて使用する必要があります。
_[ApiExplorerSettings(GroupName = "...")]
_
ただし、デフォルトでは、グループ名は特定のドキュメントに操作を含めるために使用されます。したがって、これは予期しない結果につながる可能性があります(options.SwaggerDoc(name, ...)
の呼び出しでのドキュメントの名前によって異なります)。
それを機能させるには、これを追加する必要があるかもしれません:
_options.DocInclusionPredicate((name, api) => true);
_
ここで、すべての操作について、nameはドキュメントの名前であり、グループ名は_api.GroupName
_で使用できます。グループ名に関係なくドキュメントに操作を含めるには、単にtrueを返します。