能否使用Swagger为ASP.NET MVC 5控制器提供接口文档支持？

前置准备 #

• 首先确认你的MVC5项目已经通过NuGet安装Swashbuckle.Core包，如果之前已经安装了完整的Swashbuckle包，先卸载，仅保留Swashbuckle.Core包即可，避免默认Web API适配逻辑的干扰。

步骤1：自定义可见性标记特性 #

Swagger默认只会扫描Web API控制器的接口，你可以通过自定义特性标记需要暴露到文档的MVC控制器/动作：

[AttributeUsage(AttributeTargets.Method | AttributeTargets.Class)]
public class SwaggerVisibleAttribute : Attribute
{
}

步骤2：实现自定义文档过滤器，注入MVC接口信息 #

实现IDocumentFilter接口，将符合条件的MVC动作批量添加到Swagger文档中：

public class MvcActionDocumentFilter : IDocumentFilter
{
    public void Apply(SwaggerDocument swaggerDoc, SchemaRegistry schemaRegistry, IApiExplorer apiExplorer)
    {
        // 扫描当前程序集所有MVC控制器
        var mvcControllerTypes = Assembly.GetCallingAssembly().GetTypes()
            .Where(t => typeof(Controller).IsAssignableFrom(t) && !t.IsAbstract);
        
        foreach (var controllerType in mvcControllerTypes)
        {
            // 筛选标注了SwaggerVisible、返回JsonResult的公共动作
            var actions = controllerType.GetMethods(BindingFlags.Instance | BindingFlags.Public)
                .Where(m => m.GetCustomAttribute<SwaggerVisibleAttribute>() != null
                            && m.ReturnType == typeof(JsonResult));
            
            foreach (var action in actions)
            {
                // 按项目路由规则生成接口路径，默认规则为{controller}/{action}
                var controllerName = controllerType.Name.Replace("Controller", "").ToLower();
                var actionName = action.Name.ToLower();
                var routePath = $"/{controllerName}/{actionName}";
                
                if (!swaggerDoc.paths.ContainsKey(routePath))
                {
                    // 读取动作的描述特性作为接口说明
                    var actionDesc = action.GetCustomAttribute<DescriptionAttribute>()?.Description ?? "无说明";
                    // 构造Swagger接口配置，可根据实际需求扩展参数、响应结构等信息
                    swaggerDoc.paths.Add(routePath, new PathItem
                    {
                        post = new Operation
                        {
                            tags = new List<string> { controllerName },
                            summary = actionDesc,
                            responses = new Dictionary<string, Response>
                            {
                                { "200", new Response { description = "请求成功" } }
                            }
                        }
                    });
                }
            }
        }
    }
}

步骤3：注册Swagger路由与配置 #

在Global.asax.cs的Application_Start方法中添加以下配置，暴露/swagger端点：

GlobalConfiguration.Configuration
    .EnableSwagger(c =>
    {
        c.SingleApiVersion("v1", "项目接口文档");
        // 注册自定义MVC接口扫描过滤器
        c.DocumentFilter<MvcActionDocumentFilter>();
        c.IgnoreObsoleteActions();
    })
    // 配置Swagger UI访问路径为/swagger
    .EnableSwaggerUi("swagger/{*assetPath}", c =>
    {
        // 按需关闭在线校验避免不必要的报错
        c.DisableValidator();
    });

步骤4：标记需要暴露的MVC接口 #

在对应返回JSON的MVC控制器或动作上添加[SwaggerVisible]特性即可：

public class DataController : Controller
{
    [HttpPost]
    [SwaggerVisible]
    [Description("获取分页用户数据")]
    public JsonResult GetUserList(int page = 1, int pageSize = 10)
    {
        // 业务逻辑实现
        return Json(new { code = 200, data = new List<object>() });
    }
}

注意事项 #

• 如果你的MVC接口有自定义路由、多请求方式、复杂参数等配置，需要同步调整文档过滤器中的接口信息生成逻辑，保证文档和实际接口规则一致
• 如果需要对接口参数、响应结构做更详细的描述，可以参照Swashbuckle的原生配置规则扩展Operation的相关字段

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