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 預設自帶的介面已經不見了。