列出多个组下的 API 方法 [英] Listing API Methods Under Multiple Groups

问题描述

我的 Swashbuckle 注释代码如下所示:

[Route("api/Subscribers/{id}/[controller]")][Route("api/Organizations/{id}/[controller]")]公共类地址控制器:控制器{[HttpGet("{aid}")][SwaggerResponse(HttpStatusCode.OK, Type = typeof(PostalRecord))]公共异步任务<IActionResult>GetAddress(Guid id，Guid 帮助){//做一点事}

我想使用

简而言之，地址"端点现在出现在我想要的标题下，但是，如红色箭头所示，它们现在也被交叉列出"；我不希望在组织"端点下列出订阅者"端点.

如果我可以删除交叉列出的条目，我怀疑 [SwaggerOperationFilter] 可能是答案的另一半".我以前没有玩过这种机制.

焦虑

另外，很遗憾 [SwaggerOperation] 只能应用于方法/动作.我宁愿把它应用到类本身:

[Route("api/Subscribers/{id}/[controller]")][Route("api/Organizations/{id}/[controller]")][SwaggerOperation(Tags = new []{"订阅者", "组织"})]公共类地址控制器:控制器{

有什么补救办法吗?

解决方案

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

公共类 CategorizeFilter : IOperationFilter{公共无效应用(操作操作，OperationFilterContext上下文){字符串路径 = context.ApiDescription.RelativePath;字符串段 = path.Split('/')[1];如果(段！= context.ApiDescription.GroupName){operation.Tags = 新列表<字符串>{ 分割 };}}}

然后我只是根据需要装饰我的动作:

[Route("api/Subscribers/{id}/[controller]")][Route("api/Organizations/{id}/[controller]")]公共类地址控制器:控制器{[HttpGet("{aid}")][SwaggerOperationFilter(typeof(CategorizeFilter))][SwaggerResponse(HttpStatusCode.OK, Type = typeof(PostalRecord))]公共异步任务<IActionResult>GetAddress(Guid id，Guid 帮助){//做一点事}

因此，地址"类别从我的 Swagger UI 中完全消失了(很好！)，并且端点路由的双组在组织"和订阅者"组之间正确划分.完美！

I have Swashbuckle annotated code that looks like this:

[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
    }

I would like to use the GroupActionsBy customization, as shown in this example, but I want to have the above GetAddress method simultaneously included into two separate groups that correspond to the two route prefixes shown:

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

In other words, I want the same method to be listed under both:

• Subscribers
• Organizations

How can this be done?

Incidentally, I'm working with ASP.NET Core (dnx46). If it is not yet possible to do this with the ASP.NET Core version of Swashbucklee, then a full-CLR (Web API 2.2?) example would still be appreciated.

Also, for a more complete story of what I'm trying to do - I have a separate SO post.

Update

The answer given by @venerik got me close to the solution. When I apply his sample code...

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

...this causes the Swagger listings to look like this:

In short, the "Addresses" endpoints are now appearing under the headings that I want but, as the red arrow indicates, they are now also being "cross-listed"; I don't want the "Subscribers" endpoint being listed under the "Organizations" endpoint.

I'm suspicious that a [SwaggerOperationFilter] might be "the other half" of the answer, if I can make it remove the cross-listed entries. I've not played with that mechanism before.

Angst

Also, it is very unfortunate that [SwaggerOperation] can only be applied on methods/actions. I would rather apply it to the class itself:

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

Is there any remedy for this?

解决方案

@venerik got me on the right path. But instead of a [SwaggerOperation] attribute, what I needed was a [SwaggerOperationFilter], like this:

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 };
        }
    }
}

Then I just decorate my actions as needed:

[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
    }

As a consequence, the "Addresses" category completely disappeared from my Swagger UI (good!) and the twin set of endpoint routes are properly divided between "Organizations" and "Subscribers" groups. Perfect!

这篇关于列出多个组下的 API 方法的文章就介绍到这了，希望我们推荐的答案对大家有所帮助，也希望大家多多支持IT屋！