有没有办法在swagger-ui页面中更改控制器的名称?

exdqitrt  于 2022-11-06  发布在  其他
关注(0)|答案(6)|浏览(338)

我正在使用Swashbuckle在我的WebApi项目中启用swagger和swagger-ui。
在下面的图片中,你可以看到我的两个控制器显示在swagger-ui页面中。它们的命名与它们在C#代码中的命名相同,但是我想知道是否有一种方法可以改变这里显示的内容?
这主要是因为ManagementDashboardWidget不是一个用户友好的名称,所以我想将其更改为用户友好的名称。

2g32fytz

2g32fytz1#

ASP.NET Core 6开始,您可以在控制器级别使用TagsAttribute

[Tags("entity")]
[ApiController]
public class DerivedEntitiesController : ControllerBase
{

或行动水平:

[Tags("entity")]
[HttpPut("entity/{key}")]
public IActionResult PutEntity(Guid key, [FromBody] Entity entity)
{

Swagger将根据Tags进行分组,并遵守API版本。

h43kikqp

h43kikqp2#

Swashbuckle第5版支持以下选项(用于调用AddSwaggerGen()):

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

这应该与控制器或操作上的以下属性结合使用:

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

但是,默认情况下,组名用于包含特定文档中的操作。因此,这可能会导致意外结果(取决于您在调用options.SwaggerDoc(name, ...)时对文档的命名)。
要使其正常工作,您可能需要添加以下内容:

options.DocInclusionPredicate((name, api) => true);

在这里,对于每个操作,name是文档的名称,组名在api.GroupName中可用。要在文档中包括操作而不管其组名,只需返回true。

ltqd579y

ltqd579y3#

你可以使用标记来实现。默认情况下,Swashbuckle会为每个操作添加一个带有控制器名称的标记。你可以用SwaggerOperationAttribute覆盖它。例如,下一行用标记Test替换了默认标记Values:

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

Get操作现在将被放入组Test中。
如果希望操作显示在多个组中,则可以添加更多标记。例如:

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

会将Get作业放入群组TestRelease1中。

b1zrtrql

b1zrtrql4#

我尝试使用venerik的答案,但它仍然保留了UI中的原始控制器名称沿着您指定的新标记。我也不喜欢您必须为每个函数添加一个属性,所以我想出了一个解决方案,您只需为控制器添加一个属性。有两个步骤:
在控制器上添加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库中定义的扩展方法。

aiqt4smr

aiqt4smr5#

默认情况下,如果我有一个名为ShippingController的控制器,则swagger生成的UI名称为“Shipping”
我想把我的控制器的名字改成更友好的或者用另一种语言写的。我能找到的最好的办法是用一个SwaggerOperation属性来改变名字,但是这有一个限制,那就是它是一个方法级别的属性,我真的不想在每个方法上都指定这个名字。
所以,我创建了一个约定类来与控制器的Route属性一起使用,我们通常在控制器上使用这个类,然后让swagger使用它作为控制器的名称。你知道在属性上有一个name属性,但是生成的swagger似乎没有使用它。

步骤1:创建此类:

当应用程序启动时,它将运行此命令,如果控制器具有指定的Route属性,我将能够查找该属性,然后使用name属性更改控制器的名称。

using Microsoft.AspNetCore.Mvc;
using Microsoft.AspNetCore.Mvc.ApplicationModels;

namespace RestServices.Configuration.ConfigInstallers.Conventions
{
    public class ControllerDocumentationConvention : IControllerModelConvention
    {
        void IControllerModelConvention.Apply(ControllerModel controller)
        {
            if (controller == null)
                return;

            foreach (var attribute in controller.Attributes)
            {
                if (attribute.GetType() == typeof(RouteAttribute))
                {
                    var routeAttribute = (RouteAttribute)attribute;
                    if (!string.IsNullOrWhiteSpace(routeAttribute.Name))
                        controller.ControllerName = routeAttribute.Name;
                }
            }

        }
    }
}

第2步:启动。cs:

修改StartUp.cs文件,并在配置服务中,我们需要在约定列表中注册我们的类。请参见以下内容:

services.AddControllers(o =>
{
   o.Conventions.Add(new ControllerDocumentationConvention());
});

第3步:在每个控制器的Route属性中添加名称属性:

[ApiController]
[ApiVersion("1.0")]
[ApiExplorerSettings(IgnoreApi = false, GroupName = "v1")]
[Route("api/Envios/{version:apiVersion}", Name =  "Envios", Order = 1)]
[Produces("application/json")]
public class ShippingController

现在,当我运行应用程序并生成我的swagger时,您可以看到控制器名称已更改为与route attributes name属性中的文本相同。

vuktfyat

vuktfyat6#

如果要在控制器/类级别执行此操作,下面是here中非常有用的摘录
使用控制器上的[ApiExplorer设置(组名=“组”)]
然后在启动中

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重载,它支持返回一个标记数组。这应该可以简化上面的自定义

相关问题