Question

我正在构建一个REST服务，它将托管多个控制器（微服务）。总的来说，我们可以调用服务“Bob”。因此昂首阔步地展示了“Bob”/“Bob Microservices的集合”。然后列出控制器名称。现在，它只是显示XYZ，ABC等。有没有办法可能有swagger显示“XYZ - XYZ API的集合”或类似的东西？

似乎swagger显示方法的///摘要，但不显示控制器。

Answer 1

有没有办法可能有摇摆不定的节目＆＃34; XYZ - 一系列XYZ API＆＃34;

是。这是最简单的方法之一。 Swagger的ASP.NET核心版本利用ApiExplorerSettings属性。您可以设置GroupName。

public class BobController 
{
    [ApiExplorerSettings(GroupName="XYZ - A collection of XYZ APIs")]
    public IActionResult MyAction() 
    {
        ...
    }
}

组名称显示在Swagger UI中，组的操作列在下面的操作中。

编辑：这是基于SledgeHammer评论的想法。

Swagger ASP.NET Core使用IApiDescriptionGroupCollectionProvider来构建其描述组。我们可以使用默认的ApiDescriptionGroupCollectionProvider来实现我们自己的灵感，并在Startup.ConfigureServices期间注册我们的提供商。我们的实现会使ApiDescriptionGroups()方法返回与每个操作控制器关联的GroupName。然后我们可以在每个控制器上放置ApiExplorerSettings属性而不是每个操作。

Answer 2

您也可以使用SwaggerOperationAttribute：

public class MyController 
{
    [SwaggerOperation(Tags = new[] { "XYZ - A collection of XYZ APIs" })]
    public IActionResult MyAction() 
    {
    }
}

在Swashbuckle.AspNetCore版本1.0.0-rc3中，ApiExplorerSettingsAttribute用于在特定的Swagger文档中包含操作。

Answer 3

我知道这很旧，但是以防万一有人落在这里-寻找核心版本的答案-为了完整起见，我将留下另一个简单的选择。来自docs：

自定义操作标签（例如，用于UI分组）

Swagger规范允许将一个或多个“标签”分配给一项操作。 Swagger生成器会将控制器名称分配为默认标签。如果您使用的是SwaggerUI中间件，则这特别有趣，因为它使用此值对操作进行分组。

您可以通过提供按约定应用标签的功能来覆盖默认标签。例如，以下配置将通过HTTP方法标记并因此在UI中对操作进行分组：

services.AddSwaggerGen(c =>
{
    ...
    c.TagActionsBy(api => api.HttpMethod);
};

使用这种方式，您可以使用最适合您需求的逻辑来标记端点。您将lambda传递给TagActionsBy方法，并返回所需的标签。

对于您提供的示例，我们可以做到：

services.AddSwaggerGen(c =>
{
    ...
    c.TagActionsBy(api => "XYZ - A collection of XYZ APIs");
};

希望这会有所帮助！

Answer 4

如果您使用的是Swashbuckle 4.0.x和ASP.NET Core 2.x，则可能会有类似的效果。

using System.Collections.Generic;
using Microsoft.AspNetCore.Mvc;
using Microsoft.Extensions.Logging;
using Swashbuckle.AspNetCore.Annotations;

namespace MyExample.Controllers
{
/// <summary>
/// Example of a .NET Core controller based on the controller name
/// api/[controller] on ValuesController becomes api/values
/// endpoint: "/Values" from [controller] and name of controller , which is "ValuesController"
/// </summary>
[Route("[controller]")]
[ApiController]
[SwaggerTag("This is an example controller generated by ASP.NET Core 2.x")]
public class ValuesController : ControllerBase
{
...
}

然后我的Startup.cs大写代码如下：

services.AddSwaggerGen(c =>
            {
                // Set Title and version
                c.SwaggerDoc("v1", new Info { Title = "My Example API", Version = "v1", Description = "The API for my application" });
                // Set the comments path for the Swagger JSON and UI.
                var xmlFile = $"{Assembly.GetExecutingAssembly().GetName().Name}.xml";
                var xmlPath = Path.Combine(AppContext.BaseDirectory, xmlFile);
                // pick comments from classes
                c.IncludeXmlComments(xmlPath);
                // enable the annotations on Controller classes [SwaggerTag]
                c.EnableAnnotations();
            });

然后我的控制器将被装饰

Answer 5

我一直在寻找类似的答案，希望能够在控制器类上使用XML注释摘要来提供控制器描述。事实证明，您可以通过在启动时的Swagger配置中添加includeControllerXmlComments：true来做到这一点：

    services.AddSwaggerGen(c =>
    {
        // Set the comments path for the Swagger JSON and UI.
        var xmlFile = $"{Assembly.GetExecutingAssembly().GetName().Name}.xml";
        var xmlPath = Path.Combine(AppContext.BaseDirectory, xmlFile);
        c.IncludeXmlComments(xmlPath, includeControllerXmlComments: true);
    });

然后：

    /// <summary>
    /// My controller description
    /// </summary>
    [Route("api/[controller]")]
    [ApiController]

显示为：

Swagger（Asp.Net Core）是否有控制器描述？

5 个答案:

自定义操作标签（例如，用于UI分组）