无需SwashBuckle，从apiDefinition.swagger.json生成Swagger UI的方法

一、用已生成的apiDefinition.swagger.json搭建Swagger UI #

1. 静态文件部署方式 #

• 下载Swagger UI的静态资源包，取出其中的dist文件夹，复制到你的Asp.Net Web API项目中（比如放在Content/SwaggerUI目录下）。
• 打开dist里的index.html，找到默认的Swagger JSON路径配置（类似url: "https://petstore.swagger.io/v2/swagger.json"），替换为你的apiDefinition.swagger.json相对路径，比如JSON文件在项目根目录就改成url: "../apiDefinition.swagger.json"。
• 确保项目允许访问静态文件：
  • 传统Asp.Net项目：在Web.config的<system.webServer>节点下添加配置：

    <staticContent>
      <mimeMap fileExtension=".json" mimeType="application/json" />
    </staticContent>
    

  • Owin托管项目：在Startup.cs中启用静态文件中间件：

    app.UseStaticFiles();
    

• 部署后访问/Content/SwaggerUI/index.html即可查看Swagger UI。

2. 集成到Swashbuckle加载外部JSON #

如果想用Swashbuckle框架，可手动配置加载已有JSON：

• 安装Swashbuckle.Core NuGet包。
• 在项目App_Start文件夹下手动创建SwaggerConfig.cs：

  using System.Web.Http;
  using Swashbuckle.Application;
  using Newtonsoft.Json;
  
  namespace YourApiProjectNamespace
  {
      public class SwaggerConfig
      {
          public static void Register()
          {
              GlobalConfiguration.Configuration
                  .EnableSwagger(c =>
                  {
                      c.CustomProvider((defaultProvider) => new ExternalSwaggerProvider("~/apiDefinition.swagger.json"));
                  })
                  .EnableSwaggerUi(c => { });
          }
  
          private class ExternalSwaggerProvider : ISwaggerProvider
          {
              private readonly string _swaggerPath;
  
              public ExternalSwaggerProvider(string swaggerPath)
              {
                  _swaggerPath = swaggerPath;
              }
  
              public SwaggerDocument GetSwagger(string rootUrl, string apiVersion)
              {
                  var json = System.IO.File.ReadAllText(System.Web.HttpContext.Current.Server.MapPath(_swaggerPath));
                  return JsonConvert.DeserializeObject<SwaggerDocument>(json);
              }
          }
      }
  }
  

• 在Global.asax的Application_Start中添加SwaggerConfig.Register();，启动后访问/swagger/ui/index即可加载自定义JSON。

二、其他创建Swagger UI的替代方案 #

1. 手动配置Swashbuckle扫描继承的控制器 #

针对控制器继承公共基类的场景，手动配置Swashbuckle扫描规则即可：

• 安装Swashbuckle.Core NuGet包。
• 创建SwaggerConfig.cs并配置扫描逻辑：

  using System.Web.Http;
  using Swashbuckle.Application;
  using YourSharedProjectNamespace; // 引入公共控制器命名空间
  
  namespace YourApiProjectNamespace
  {
      public class SwaggerConfig
      {
          public static void Register()
          {
              GlobalConfiguration.Configuration
                  .EnableSwagger(c =>
                  {
                      c.SingleApiVersion("v1", "你的API名称");
                      // 扫描所有继承自公共控制器的类
                      c.SelectControllers(type => type.IsSubclassOf(typeof(YourBaseApiController)));
                      // 可选：添加XML注释路径
                      // c.IncludeXmlComments(System.Web.HttpContext.Current.Server.MapPath("~/bin/YourApiProject.XML"));
                      // 解决Action冲突
                      c.ResolveConflictingActions(apiDescriptions => apiDescriptions.First());
                  })
                  .EnableSwaggerUi(c => { });
          }
      }
  }
  

• 在Global.asax中注册配置，Swashbuckle会自动生成Swagger文档及UI。

2. 使用NSwag框架 #

NSwag对Asp.Net Web API的继承场景兼容性更好：

• 安装NSwag.AspNet.WebApi NuGet包。
• 在Global.asax的Application_Start中添加配置：

  using NSwag.AspNet.WebApi;
  
  protected void Application_Start()
  {
      GlobalConfiguration.Configure(config =>
      {
          config.EnableSwaggerDocument(settings =>
          {
              settings.Title = "你的API";
              settings.Version = "v1";
              // 指定扫描公共控制器所在程序集
              settings.GeneratorSettings.Controllers.Add(typeof(YourBaseApiController).Assembly);
          });
          config.EnableSwaggerUi();
      });
  }
  

• 启动项目后访问/swagger即可查看NSwag生成的Swagger UI。

3. 在线Swagger UI加载本地JSON #

临时查看的话，可将apiDefinition.swagger.json放到本地静态服务器，然后在Swagger UI在线编辑器中输入该JSON的访问URL，即可加载并查看UI。

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