ASP.NET Web API 中使用 swagger 来管理 API 文档

本文以 ASP.NET Web API 为后台框架，利用 EF6 连接 postgreSQL 数据库，使用 swagger 来生成 REST APIs文档。文章分二个部分，第一部分主要讲如何用 EF6 连接 postgreSQL，第二部分是介绍如何集成 swagger，如何屏蔽 swagger 默认自带的接口说明。

一、EF6 连接 postgreSQL

（1）使用 NuGet 安装 Npgsql.EntityFramework

在VS的程序包管理控制台输入如下命令

Install-Package Npgsql.EntityFramework

（2）配置 Web.config

利用 NuGet 安装的 EntityFramework，大部分配置都会自动在 Web.config 中生成，但却不会生成 DbProviderFactories，咱们手动把 DbProviderFactories 加上。数据库的连接信息也需要手动配置，在这里一并配置。配置如下：

 <system.data>
     <DbProviderFactories>
         <remove invariant="Npgsql" />
         <add name="Npgsql" invariant="Npgsql" description=".Net Framework Data Provider for Postgresql" type="Npgsql.NpgsqlFactory, Npgsql" />
     </DbProviderFactories>
 </system.data>
 <connectionStrings>
     <!--  数据库连接字符串, 包含主机,端口,用户,密码 -->
     <add name="DbConn" connectionString="Server=localhost;Port=5432;User Id=postgres; Password = postgres; Database=postgres" providerName="Npgsql"/>
 </connectionStrings>

（3）新建 数据库上下文（DbContext）类

 // 数据库上下文 DB.cs
 public class DB : DbContext
 {
     public DB() : base("name = DbConn") {}
     protected override void OnModelCreating(DbModelBuilder modelBuilder)
     {
         //设置 EF 的默认schema
         modelBuilder.HasDefaultSchema("public");
     }
     // 实体类 (demo为表名)
     public virtual DbSet<demo> demo { get; set; }
 }

（4）新建实体类 demo

 public class demo
 {
     [Key]
     [DatabaseGenerated(DatabaseGeneratedOption.Identity)]
     public string id { get; set; }
 
     [Required]
     public string name { get; set; }
 }

（5）改写 ValuesController

 public List<demo> Get()
 {
     using (DB db = new DB())
     {
         return db.demo.ToList();
     }
 }

（7）测试数据连接是否正常

浏览器中输入 http://localhost:46665/api/Values，如果能看到有数据库中的数据返回，表示数据访问正常。

二、集成 swagger

（1）安装  swagger

Install-Package Swashbuckle

（2）配置 xml 生成 路径

选中项目—>右键—>项目属性—>生成—>勾选(XML文档文件)—>保存

（3）查看结果

浏览器中输入 http://localhost:46665/swagger/ui/index

PS：运行中如果出现错误，找到 SwaggerNet 类，注释类上面的两行

// [assembly: WebActivator.PreApplicationStartMethod(typeof(webApi.App_Start.SwaggerNet), "PreStart")]
// [assembly: WebActivator.PostApplicationStartMethod(typeof(webApi.App_Start.SwaggerNet), "PostStart")]    

（4）swagger 中显示接口注释信息

 public class SwaggerConfig
 {
     public static void Register()
     {
         var thisAssembly = typeof(SwaggerConfig).Assembly;
 
         GlobalConfiguration.Configuration
             .EnableSwagger(c =>{
                                c.SingleApiVersion("v1", "webApi");
                                //添加XML解析
                                //注意修改相应的XML名字
                                c.IncludeXmlComments(string.Format("{0}/bin/webApi.XML", System.AppDomain.CurrentDomain.BaseDirectory));
              }).EnableSwaggerUi(c =>{});
     }
 }

到此，swagger 已经能生成文档了，但这时候生成的文档中会包含 swagger 默认自带的接口，看起来有点别扭。下面介绍下屏蔽 swagger 默认自带的接口。

在 SwaggerConfig 中添加 DocumentFilter。

 public class SwaggerConfig
 {
     public static void Register()
     {
         var thisAssembly = typeof(SwaggerConfig).Assembly;
 
         GlobalConfiguration.Configuration
             .EnableSwagger(c =>{
                                c.SingleApiVersion("v1", "webApi");
                                //添加XML解析
                                //注意修改相应的XML名字
                                c.IncludeXmlComments(string.Format("{0}/bin/webApi.XML", System.AppDomain.CurrentDomain.BaseDirectory));
                                // 接口过滤
                                c.DocumentFilter<ApiFilter>();
              }).EnableSwaggerUi(c =>{});
     }
 }

 // ApiFilter.cs
 [AttributeUsage(AttributeTargets.Method | AttributeTargets.Class)]
 public partial class ApiAttribute : Attribute { }
 public class ApiFilter: IDocumentFilter
 {
     public void Apply(SwaggerDocument swaggerDoc, SchemaRegistry schemaRegistry, IApiExplorer apiExplorer)
     {
          foreach (ApiDescription apiDescription in apiExplorer.ApiDescriptions)
          {
             // url 过滤
             var _key = "/" + apiDescription.RelativePath.TrimEnd('/');
             if (_key.Contains("/api/Swagger") && swaggerDoc.paths.ContainsKey(_key))
                swaggerDoc.paths.Remove(_key);
           }
     }
 }

重新运行下，swagger 默认自带的接口已经不见了。