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 默認自帶的接口已經不見了。