如何使用Swashbuckle为OAS3定义Links？Swagger UI v3功能适配咨询

我之前帮几个项目落地过这个功能，只要配置到位，就能在 Swagger UI v3 里完美展示和使用 Links 特性。下面是具体的实现步骤和示例：

1. 先确认 Swashbuckle 版本 #

你需要使用 Swashbuckle.AspNetCore v5.0.0 及以上版本——这个版本开始全面支持 OpenAPI 3.0 规范。如果项目还在用旧版本，先通过 NuGet 更新这两个核心包：

• Swashbuckle.AspNetCore.Swagger
• Swashbuckle.AspNetCore.SwaggerUI

2. 配置 Swagger 生成器为 OAS3 格式 #

在项目的启动配置文件（.NET 6+ 是 Program.cs，旧版本是 Startup.cs）中，确保 Swagger 生成器启用 OpenAPI 3.0：

builder.Services.AddSwaggerGen(options =>
{
    options.SwaggerDoc("v1", new OpenApiInfo 
    { 
        Title = "你的API名称", 
        Version = "v1",
        Description = "支持OAS3 Links功能的示例API"
    });
});

3. 通过自定义操作过滤器添加 Links #

Swashbuckle 没有内置特性直接添加 Links，但可以通过操作过滤器实现，这是最灵活易维护的方式。举个常见场景：创建资源后，在 201 响应中添加指向该资源详情的链接。

示例场景：创建订单后链接到订单详情 #

假设你有两个接口：

• POST /orders：创建订单，返回 201 Created
• GET /orders/{id}：获取指定ID的订单详情

步骤3.1：编写操作过滤器

创建一个过滤器类，用来给指定接口的响应添加 Links：

public class ResourceLinksFilter : IOperationFilter
{
    public void Apply(OpenApiOperation operation, OperationFilterContext context)
    {
        // 匹配创建订单的接口
        var actionDescriptor = context.ApiDescription.ActionDescriptor;
        if (actionDescriptor.RouteValues["controller"] == "Orders" && 
            actionDescriptor.RouteValues["action"] == "CreateOrder")
        {
            // 找到201响应
            if (operation.Responses.TryGetValue("201", out var createdResponse))
            {
                // 定义指向GetOrder接口的链接
                var getOrderLink = new OpenApiLink
                {
                    OperationId = "GetOrder", // 对应GetOrder接口的OperationId
                    Parameters = new Dictionary<string, OpenApiAny>
                    {
                        // {id}会自动关联响应体中的id字段
                        ["id"] = new OpenApiString("{id}")
                    },
                    Description = "点击获取刚创建的订单详情",
                    Server = operation.Servers.FirstOrDefault()
                };

                // 将链接添加到响应的Links集合中
                createdResponse.Links.Add("GetOrder", getOrderLink);
            }
        }
    }
}

步骤3.2：注册过滤器

在 AddSwaggerGen 中注册这个过滤器，同时确保接口的 OperationId 正确生成：

builder.Services.AddSwaggerGen(options =>
{
    options.SwaggerDoc("v1", new OpenApiInfo { Title = "订单API", Version = "v1" });
    // 注册自定义过滤器
    options.OperationFilter<ResourceLinksFilter>();
    // 确保OperationId唯一且可识别
    options.CustomOperationIds(apiDesc => 
        $"{apiDesc.ActionDescriptor.RouteValues["controller"]}_{apiDesc.ActionDescriptor.RouteValues["action"]}");
});

4. 验证效果 #

启动项目打开 Swagger UI，调用 POST /orders 接口得到 201 响应后，你会在响应区域看到一个 Links 板块，里面包含你定义的 "GetOrder" 链接。点击链接会自动跳转到 GET /orders/{id} 接口，并将响应中的 id 自动填充到参数中，体验非常流畅！

补充说明 #

• 如果需要给多个接口添加 Links，只需在过滤器中扩展匹配逻辑即可。
• 也可以直接在接口代码中手动构建 OpenApiResponse 并添加 Links，但过滤器的方式更适合批量管理。
• 我身边不少.NET开发者都用这种方式成功实现了 Links 功能，只要版本和配置没问题，完全可以正常工作。

内容的提问来源于stack exchange，提问作者Inx51