.NET Core WebApi幫助文檔使用Swagger生成Api說明文檔

Swagger也稱為Open API，Swagger從API文檔中手動完成工作，並提供一系列用於生成，可視化和維護API文檔的解決方案。簡單的說就是一款讓你更好的書寫API文檔的框架。

我們為什么選擇swagger，現在的網站開發結果越來越注重前后端的分離，比如以前的webFrom到現在的mvc模式都是為了這個前后端的分離。就算再如何的分離實現，也是不可避免的要進行數據交互的，那么接口的重要性就提現出來了。他成了前端和后端交互的重要途徑，API文檔也因此成了前端開發人員與后端開發人員的重要紐帶。所有我們有一個API文檔框架豈不是美哉。

Swashbuckle有三個主要組件：

Swashbuckle.AspNetCore.Swagger：Swagger對象模型和中間件，將SwaggerDocument對象公開為JSON端點。
Swashbuckle.AspNetCore.SwaggerGen：一種Swagger生成器，可SwaggerDocument直接從路由，控制器和模型構建對象。它通常與Swagger端點中間件結合使用，以自動公開Swagger JSON。
Swashbuckle.AspNetCore.SwaggerUI：Swagger UI工具的嵌入式版本。它將Swagger JSON解釋為構建豐富的，可定制的Web API功能描述體驗。它包括用於公共方法的內置測試線束。

如何使用vs2019安裝Swashbuckle

從“管理 NuGet 程序包”對話框中或“程序包管理器控制台”窗口進行安裝。

從“程序包管理器控制台”窗口進行安裝：

• 轉到“視圖” > “其他窗口” > “程序包管理器控制台”
• 將“默認項目”改為需要添加的項目。
• 輸入命令 ·Install-Package Swashbuckle.AspNetCore

從“管理 NuGet 程序包”對話框中：

• 右鍵單擊“解決方案資源管理器” > “管理 NuGet 包”中的項目
• 將“包源”設置為“nuget.org”
• 在搜索框中輸入“Swashbuckle.AspNetCore”
• 從“瀏覽”選項卡中選擇“Swashbuckle.AspNetCore”包，然后單擊“安裝”

如果你看到這段文字，說明您正使用RSS閱讀或轉自《一棵樹-博客園》，原文地址：https://www.cnblogs.com/atree/p/netcore-WebApi-Swagger.html

添加並配置Swagger中間件

然后配置Startup.cs 文件中的ConfigureServices方法。

//不要忘記引用一下using Swashbuckle.AspNetCore.Swagger命名空間，不然info類會報錯
using Swashbuckle.AspNetCore.Swagger

public void ConfigureServices(IServiceCollection services) 
{
    services.AddMvc()
        .SetCompatibilityVersion (CompatibilityVersion.Version_2_1)
        .AddJsonOptions (options =>
            options.SerializerSettings.ContractResolver =
            new Newtonsoft.Json.Serialization.DefaultContractResolver ()); //JSON首字母小寫解決;

    //注冊Swagger生成器，定義一個和多個Swagger 文檔
    services.AddSwaggerGen(c => 
    {
        c.SwaggerDoc ("v1", new Info { Title = "My API", Version = "v1" });
    });
}

然后在Configure方法中添加：

//允許中間件為JSON端點服務生成的Siggg
app.UseSwagger ();
//使中間件能夠服務於輕量級用戶界面（HTML、JS、CSS等），並指定SWAGJER JSON端點
app.UseSwaggerUI (c => {
    c.SwaggerEndpoint ("/swagger/v1/swagger.json", "My API V1");
    // 要在應用程序的根處提供Swagger UI ，請將該RoutePrefix屬性設置為空字符串
    c.RoutePrefix = string.Empty;
});

 啟動應用，並導航到 http://localhost:<port>/swagger/v1/swagger.json。 生成的描述終結點的文檔顯示如下json格式。

可在 http://localhost:<port>/swagger 找到 Swagger UI。也可設置其他地址，我把他配置成了根節點，這樣直接啟動根節點就是該頁面。主要是上面代碼中的： c.RoutePrefix = string.Empty這句代碼。

我們可以擴展一些附加信息，比如作者，許可證，服務條款等。傳遞給該AddSwaggerGen方法的配置：

//Swagger生成器添加到方法中的服務集合中
services.AddSwaggerGen (options => {
    options.SwaggerDoc ("v1", new Info {
        Version = "v1",
            Title = " API 文檔",
            Description = "這是一個示例webapi文檔",
            //服務條款
            TermsOfService = "None Services",
            //作者信息
            Contact = new Contact {
                Name = "atree",
                    Email = string.Empty,
                    Url = "https://www.cnblogs.com/atree/"
            },
            //許可證
            License = new License {
                Name = "許可證名字",
                    Url = "http://www.cnblogs.com/atree/"
            }
    });

});

為接口增加注釋

啟用XML注釋可為未記錄的公共類型和成員提供調試信息。未記錄的類型和成員由警告消息指示。配置Swagger以使用生成的XML文件。

在我們實現前先設置一下項目屬性：

這樣就可以在項目bin下生成xml文件了。下面進行代碼配置啟用，還是在Startup類中的ConfigureServices方法中，在我們剛才配置的下面在增加以下代碼：

// 設置SWAGER JSON和UI的注釋路徑。
var xmlFile = $"{Assembly.GetExecutingAssembly().GetName().Name}.xml";
var xmlPath = Path.Combine (AppContext.BaseDirectory, xmlFile);
options.IncludeXmlComments (xmlPath);

使用反射主要是為了生成一個與項目文件名相同的xml文件。第二部然后是配置文件路徑。這些配置好了以后。我們就可以把方法或者類的三道斜杠（“///”）的注釋添加到動作。我們來看一下效果。

好了，這樣在.NET Core WebApi項目中，使用Swagger生成api說明文檔已經完成了。如果需要對外展示，還可以修改UI界面，還沒有試過。對內部用，這樣就可以了。