在多个组下列出 API 个方法

Question

我有 Swashbuckle 注释代码，如下所示：

[Route("api/Subscribers/{id}/[controller]")]
[Route("api/Organizations/{id}/[controller]")]
public class AddressesController : Controller
{
    [HttpGet("{aid}")]
    [SwaggerResponse(HttpStatusCode.OK, Type = typeof(PostalRecord))]
    public async Task<IActionResult> GetAddress(Guid id, Guid aid)
    {
       //do something
    }

我想使用，但我想将上述 GetAddress 方法同时包含到两个单独的组中，这两个组对应于显示的两个路由前缀：

[Route("api/Subscribers/{id}/[controller]")]
[Route("api/Organizations/{id}/[controller]")]

换句话说，我希望相同的方法在两者下列出：

订阅者
组织

如何做到这一点？

顺便说一下，我正在使用 ASP.NET Core (dnx46)。如果还不能用 ASP.NET Core 版本的 Swashbucklee 做到这一点，那么 full-CLR（Web API 2.2？）示例仍然值得赞赏。

此外，为了更完整地说明我正在尝试做的事情 - 我有一个 separate SO post。

更新

@venerik 给出的答案让我接近了解决方案。当我应用他的示例代码时...

[SwaggerOperation(Tags = new []{"Subscribers", "Organizations"})]

...这会导致 Swagger 列表如下所示：

简而言之，"Addresses" 端点现在出现在我想要的标题下，但是，如红色箭头所示，它们现在也是 "cross-listed"；我不希望 "Subscribers" 端点列在 "Organizations" 端点下。

我怀疑 [SwaggerOperationFilter] 可能是 "the other half" 的答案，如果我可以让它删除 cross-listed 条目。我以前没玩过那个机制。

焦虑

还有，非常遗憾的是[SwaggerOperation]只能在methods/actions上应用。我宁愿将它应用于 class 本身：

[Route("api/Subscribers/{id}/[controller]")]
[Route("api/Organizations/{id}/[controller]")]
[SwaggerOperation(Tags = new []{"Subscribers", "Organizations"})]
public class AddressesController : Controller
{

有什么补救办法吗？

Answer 1

我还没有使用 ASP.NET Core 的经验，但在 ASP.NET Web API 中，您可以使用 SwaggerOperationAttribute 实现这一点。您可以使用此属性向操作添加标签。例如，下一段代码添加标签 Subscribers 和 Organizations:

[SwaggerOperation(Tags = new []{"Subscribers", "Organizations"})]
public async Task<IActionResult> GetAddress(Guid id, Guid aid)
{
   //do something
}

Swagger-UI 按标签对操作进行分组，因此，GetAddress 将同时列在 Subscribers 和 Organizations 下。

Answer 2

@venerik 让我走上了正确的道路。但是我需要的不是 [SwaggerOperation] 属性，而是 [SwaggerOperationFilter]，如下所示：

public class CategorizeFilter : IOperationFilter
{
    public void Apply(Operation operation, OperationFilterContext context)
    {
        string path = context.ApiDescription.RelativePath;
        string segment = path.Split('/')[1];

        if (segment != context.ApiDescription.GroupName)
        {
            operation.Tags = new List<string> { segment };
        }
    }
}

然后我根据需要装饰我的动作：

[Route("api/Subscribers/{id}/[controller]")]
[Route("api/Organizations/{id}/[controller]")]
public class AddressesController : Controller
{
    [HttpGet("{aid}")]
    [SwaggerOperationFilter(typeof(CategorizeFilter))]
    [SwaggerResponse(HttpStatusCode.OK, Type = typeof(PostalRecord))]
    public async Task<IActionResult> GetAddress(Guid id, Guid aid)
    {
       //do something
    }

因此，"Addresses" 类别从我的 Swagger UI 中完全消失了（很好！）并且端点路由的孪生集在 "Organizations" 和 [=22 之间正确划分=] 组。完美！

在多个组下列出 API 个方法

Listing API Methods Under Multiple Groups

c#

asp.net-web-api

asp.net-core

swagger

swashbuckle

更新

焦虑