本文是根據角落的白板報的《使用ABP實現SwaggerUI,生成動態webapi》一文的學習總結，感謝原文作者角落的白板報。

1 安裝Swashbuckle.core

1.1 選擇WebApi項目，右鍵“管理NuGet程式包”。

1.2 輸入 “Swashbuckle.core”，搜索。選擇Swashbuckle.core，右邊點擊安裝。

 2 配置Swashbuckle

 2.1 打開WebApi項目中的DemoWebApiModule.cs文件。創建ConfigureSwaggerUI()方法，併在Initialize()中調用。

public void ConfigureSwaggerUI()
{
    Configuration.Modules.AbpWebApi().HttpConfiguration
        .EnableSwagger(c =>
        {
            c.SingleApiVersion("v1", "DemoAPI文檔");
            c.ResolveConflictingActions(apiDescriptions => apiDescriptions.First());
        })
        .EnableSwaggerUi();
}

public override void Initialize()
{
    IocManager.RegisterAssemblyByConvention(Assembly.GetExecutingAssembly());

    Configuration.Modules.AbpWebApi().DynamicApiControllerBuilder
        .ForAll<IApplicationService>(typeof(DemoApplicationModule).Assembly, "app")
        .Build();

    Configuration.Modules.AbpWebApi().HttpConfiguration.Filters.Add(new HostAuthenticationFilter("Bearer"));

    ConfigureSwaggerUI();
}

2.2 運行項目。

運行項目，打開地址“/swagger/ui/index”，即可查看WebApi。

3 增強WebApi文檔

3.1 打開Application項目的屬性設置，勾選“XML文檔文件”。

 3.2 將application層中的註釋添加到SwaggerUI中。

 1 public void ConfigureSwaggerUI()
 2 {
 3     Configuration.Modules.AbpWebApi().HttpConfiguration
 4         .EnableSwagger(c =>
 5         {
 6             c.SingleApiVersion("v1", "DemoAPI文檔");
 7             c.ResolveConflictingActions(apiDescriptions => apiDescriptions.First());
 8 
 9             //將application層中的註釋添加到SwaggerUI中
10             var baseDirectory = AppDomain.CurrentDomain.BaseDirectory;
11 
12             var commentsFileName = "Bin//Demo.Application.xml";
13             var commentsFile = Path.Combine(baseDirectory, commentsFileName);
14             //將註釋的XML文檔添加到SwaggerUI中
15             c.IncludeXmlComments(commentsFile);
16         })
17         .EnableSwaggerUi();
18 }

3.3 在API介面方法中添加註釋後，SwaggerUI就會顯示對應的註釋信息。以Role為例，添加註釋如下：

UpdateRolePermissionsInput.cs

/// <summary>
/// 修改角色許可權信息接收的DTO
/// </summary>
public class UpdateRolePermissionsInput
{
    /// <summary>
    /// 角色ID
    /// </summary>
    [Range(1, int.MaxValue)]
    public int RoleId { get; set; }

    /// <summary>
    /// 獲取許可權名稱列表
    /// </summary>
    [Required]
    public List<string> GrantedPermissionNames { get; set; }
}

IRoleAppService.cs

/// <summary>
/// 角色信息介面
/// </summary>
public interface IRoleAppService : IApplicationService
{
    /// <summary>
    /// 修改角色的許可權信息
    /// </summary>
    /// <param name="input"></param>
    /// <returns></returns>
    Task UpdateRolePermissions(UpdateRolePermissionsInput input);
}

3.4 再次運行項目，可以看到WebApi文檔出現了註釋信息。

4 修改訪問方式

4.1 使用EnableSwaggerUi的重載方法。

SwaggerUI預設使用的是EnableSwaggerUi()方法，訪問路徑預設為“/swagger/ui/index/”。 F12轉到定義，我們可以看到EnableSwaggerUi有一個重載方法。

public void EnableSwaggerUi(Action<SwaggerUiConfig> configure = null);
public void EnableSwaggerUi(string routeTemplate, Action<SwaggerUiConfig> configure = null);

ConfigureSwaggerUI中更改EnableSwaggerUi()為：

EnableSwaggerUi("apis/{*assetPath}");

4.2 更改後的訪問路徑變為"apis/index"，運行程式，查看。

5 界面優化

5.1 調整界面CSS樣式

（1）新建style.css樣式文件，可以自定義文件名。

（2）style.css中編輯樣式腳本，以下為示例：

.swagger-section #header {
    background-color: #ff6a00;
    padding: 14px;
}

（3）style.css文件屬性設置為“嵌入的資源”。   非常重要！！！

（4）修改ConfigureSwaggerUI方法。

EnableSwaggerUi("apis/{*assetPath}", c=>
        {
            c.InjectStylesheet(Assembly.GetExecutingAssembly(),
                "Demo.SwaggerUI.css.style.css");
        });

其中，Demo為項目命名空間，Demo以後的為文件夾或文件。 

（5）預覽效果，可以看到header背景色由預設的綠色改為了橙色。

 5.2 漢化

操作與5.1相似。

（1）新建swagger.js文件，可以自定義文件名。

（2）編輯swagger.js。

$(function () {

    $("#logo").text("Demo");
    $("#logo").attr("href", "http://www.Demo.com");

    $("#explore").text("查詢");

    $(".options .toggleEndpointList").each(function () {
        $(this).text("展開/隱藏");
    });
    $(".options .collapseResource").each(function () {
        $(this).text("顯示資源列表");
    });

    $(".options .expandResource").each(function () {
        $(this).text("顯示資源明細");
    });

    $(".operations .description-link").each(function () {
        $(this).text("實體模型");
    });

    $(".operations .snippet-link").each(function () {
        $(this).text("實體類型");
    });

    $(".operations .response-content-type label").each(function () {
        $(this).text("請求方式");
    });
    $(".operations .sandbox h4").each(function () {
        $(this).text("參數列表");
    });

    $(".operations .response_hider").each(function () {
        $(this).text("隱藏響應界面");
    });
    $(".operations .response .curl").each(function () {
        $(this).text("請求頭");
    });

    $(".operations .response .curl").each(function () {
        $(this).next().text("請求路徑");
    });

    $(".response_body").each(function () {
        $(this).prev().text("響應正文");
    });

    $("[class='block response_code']").each(function () {
        $(this).prev().text("響應代碼");
    });

    $("[class='block response_headers']").each(function () {
        $(this).prev().text("響應標頭");
    });

    $(".parameter-content-type div label").each(function () {
        $(this).text("參數的內容類型︰");
    });

    $("small.notice").each(function () {
        $(this).text("單擊要設置為參數值");
    });

    $(".body-textarea").each(function () {
        var op = $(this).attr("placeholder");

        if (op === "(required)") {
            $(this).attr("placeholder", "(不可為空)");
        }
    });

    $(".body-textarea required");

    $(".fullwidth thead tr th").each(function () {
        var key = $(this).text();
        switch (key) {
            case "Parameter":
                $(this).text("參數名");
                break;
            case "Value":
                $(this).text("參數值");
                break;
            case "Description":
                $(this).text("描述");
                break;
            case "Parameter Type":
                $(this).text("參數類型");
                break;
            case "Data Type":
                $(this).text("數據類型");
                break;

            default:
                break;
        }
    });

    $("input[type='submit']").val("測試");
})

 其中，logo換成了文字“Demo”，logo的鏈接換成了“http://www.Demo.com”。可根據實際修改。

（3）swagger.js文件屬性設置為“嵌入的資源”。

（4）修改ConfigureSwaggerUI方法。

EnableSwaggerUi("apis/{*assetPath}", c=>
        {
            c.InjectStylesheet(Assembly.GetExecutingAssembly(),
                "Demo.SwaggerUI.css.style.css");
            c.InjectJavaScript(Assembly.GetExecutingAssembly(),
                "Demo.SwaggerUI.script.swagger.js");
        });

其中，Demo為項目命名空間，Demo以後的為文件夾或文件。

（5）預覽效果。

 後記：

       在整個過程中，我遇到的問題是，css文件和js文件設置未生效。琢磨了很久，根本原因是未設置文件屬性為“嵌入的資源”！牢記這一步！

 本節源碼鏈接：http://pan.baidu.com/s/1nuZHJvz 密碼：a0tu