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 加上。資料庫的連接信息也需要手動配置，在這裡一併配置。配置如下：

 1 <system.data>
 2     <DbProviderFactories>
 3         <remove invariant="Npgsql" />
 4         <add name="Npgsql" invariant="Npgsql" description=".Net Framework Data Provider for Postgresql" type="Npgsql.NpgsqlFactory, Npgsql" />
 5     </DbProviderFactories>
 6 </system.data>
 7 <connectionStrings>
 8     <!--  資料庫連接字元串, 包含主機,埠,用戶,密碼 -->
 9     <add name="DbConn" connectionString="Server=localhost;Port=5432;User Id=postgres; Password = postgres; Database=postgres" providerName="Npgsql"/>
10 </connectionStrings>

（3）新建 資料庫上下文（DbContext）類

 1 // 資料庫上下文 DB.cs
 2 public class DB : DbContext
 3 {
 4     public DB() : base("name = DbConn") {}
 5     protected override void OnModelCreating(DbModelBuilder modelBuilder)
 6     {
 7         //設置 EF 的預設schema
 8         modelBuilder.HasDefaultSchema("public");
 9     }
10     // 實體類 (demo為表名)
11     public virtual DbSet<demo> demo { get; set; }
12 }

（4）新建實體類 demo

1 public class demo
2 {
3     [Key]
4     [DatabaseGenerated(DatabaseGeneratedOption.Identity)]
5     public string id { get; set; }
6 
7     [Required]
8     public string name { get; set; }
9 }

（5）改寫 ValuesController

1 public List<demo> Get()
2 {
3     using (DB db = new DB())
4     {
5         return db.demo.ToList();
6     }
7 }

（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 中顯示介面註釋信息

 1 public class SwaggerConfig
 2 {
 3     public static void Register()
 4     {
 5         var thisAssembly = typeof(SwaggerConfig).Assembly;
 6 
 7         GlobalConfiguration.Configuration 
 8             .EnableSwagger(c =>{
 9                                c.SingleApiVersion("v1", "webApi");
10                                //添加XML解析
11                                //註意修改相應的XML名字
12                                c.IncludeXmlComments(string.Format("{0}/bin/webApi.XML", System.AppDomain.CurrentDomain.BaseDirectory));
13              }).EnableSwaggerUi(c =>{});
14     }
15 }

到此，swagger 已經能生成文檔了，但這時候生成的文檔中會包含 swagger 預設自帶的介面，看起來有點彆扭。下麵介紹下屏蔽 swagger 預設自帶的介面。

在 SwaggerConfig 中添加 DocumentFilter。

 1 public class SwaggerConfig
 2 {
 3     public static void Register()
 4     {
 5         var thisAssembly = typeof(SwaggerConfig).Assembly;
 6 
 7         GlobalConfiguration.Configuration 
 8             .EnableSwagger(c =>{
 9                                c.SingleApiVersion("v1", "webApi");
10                                //添加XML解析
11                                //註意修改相應的XML名字
12                                c.IncludeXmlComments(string.Format("{0}/bin/webApi.XML", System.AppDomain.CurrentDomain.BaseDirectory));
13                                // 介面過濾
14                                c.DocumentFilter<ApiFilter>();
15              }).EnableSwaggerUi(c =>{});
16     }
17 }

 1 // ApiFilter.cs
 2 [AttributeUsage(AttributeTargets.Method | AttributeTargets.Class)]   
 3 public partial class ApiAttribute : Attribute { }
 4 public class ApiFilter: IDocumentFilter
 5 {
 6     public void Apply(SwaggerDocument swaggerDoc, SchemaRegistry schemaRegistry, IApiExplorer apiExplorer)
 7     {
 8          foreach (ApiDescription apiDescription in apiExplorer.ApiDescriptions)
 9          {        
10             // url 過濾
11             var _key = "/" + apiDescription.RelativePath.TrimEnd('/');
12             if (_key.Contains("/api/Swagger") && swaggerDoc.paths.ContainsKey(_key))
13                swaggerDoc.paths.Remove(_key);
14           }
15     }
16 }

重新運行下，swagger 預設自帶的介面已經不見了。