Asp.Net Core Web Api 使用 Swagger 生成 api 說明文檔

　　最近使用 Asp.Net Core Web Api 開發項目服務端。Swagger 是最受歡迎的 REST APIs 文檔生成工具之一，進入個人視野。如下爲學習應用狀況的整理。

1、Swagger 介紹

　　使用 Swagger 做爲 REST APIs 文檔生成工具的優勢有哪些？

1. Swagger 能夠生成一個具備互動性的API控制檯，開發者能夠用來快速學習和嘗試API。
2. Swagger 能夠生成客戶端SDK代碼用於各類不一樣的平臺上的實現。
3. Swagger 文件能夠在許多不一樣的平臺上從代碼註釋中自動生成。
4. Swagger 有一個強大的社區，裏面有許多強悍的貢獻者。

　　在 Asp.Net Core 中如何使用Swagger生成api說明文檔?

1. Swashbuckle.AspNetCore 是一個開源項目，用於生成 ASP.NET Core Web API 的 Swagger 文檔。
2. NSwag 是另外一個用於將 Swagger UI 或 ReDoc 集成到 ASP.NET Core Web API 中的開源項目。 它提供了爲 API 生成 C# 和 TypeScript 客戶端代碼的方法。

　　Swashbuckle 由哪些組成部分呢？

1. Swashbuckle.AspNetCore.Swagger：將 SwaggerDocument 對象公開爲 JSON 終結點的 Swagger 對象模型和中間件。
2. Swashbuckle.AspNetCore.SwaggerGen：從路由、控制器和模型直接生成 SwaggerDocument 對象的 Swagger 生成器。 它一般與 Swagger 終結點中間件結合，以自動公開 Swagger JSON。
3. Swashbuckle.AspNetCore.SwaggerUI：Swagger UI 工具的嵌入式版本。 它解釋 Swagger JSON 以構建描述 Web API 功能的可自定義的豐富體驗。 它包括針對公共方法的內置測試工具。

2、在項目中安裝 Swashbuckle

　一、安裝 Swashbuckle 插件

　　方法1：從「程序包管理器控制檯」窗口進行安裝

1. 轉到「視圖」 > 「其餘窗口」 > 「程序包管理器控制檯」
2. 導航到包含 xxx.csproj 文件的目錄
3. 請執行如下命令 ·Install-Package Swashbuckle.AspNetCore

　　方法2：從「管理 NuGet 程序包」對話框中：

1. 右鍵單擊「解決方案資源管理器」 > 「管理 NuGet 包」中的項目
2. 將「包源」設置爲「nuget.org」
3. 在搜索框中輸入「Swashbuckle.AspNetCore」
4. 從「瀏覽」選項卡中選擇「Swashbuckle.AspNetCore」包，而後單擊「安裝」

　　

　二、添加並配置 Swagger 中間件

　　（1）Startup.cs 文件中引入「using Swashbuckle.AspNetCore.Swagger;」命名空間；
　　（2）將 Swagger 生成器添加到 Startup.ConfigureServices 方法中的服務集合中：

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

　　（3）在 Startup.Configure 方法中，啓用中間件生成的 JSON 文檔和 Swagger UI 提供服務：

//啓用中間件服務生成Swagger做爲JSON終結點
app.UseSwagger();
//啓用中間件服務對swagger-ui，指定Swagger JSON終結點
app.UseSwaggerUI(c =>
{
    c.SwaggerEndpoint("/swagger/v1/swagger.json", "基礎服務 API V1");
});

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

　　（5）可在 http://localhost:<port>/swagger/index.html 找到 Swagger UI。 經過 Swagger UI 瀏覽 API文檔，以下所示。

　　（6）要在應用的根 (http://localhost:<port>/) 處提供 Swagger UI，請將 RoutePrefix 屬性設置爲空字符串：

app.UseSwaggerUI(c =>
{
    c.SwaggerEndpoint("/swagger/v1/swagger.json", "基礎服務API V1");
    c.RoutePrefix = string.Empty;
});

3、Swagger的高級用法

 　　一、在 AddSwaggerGen 方法的進行以下的配置操做會添加諸如做者、許可證和說明信息等：

//註冊Swagger生成器，定義一個和多個Swagger 文檔
services.AddSwaggerGen(c =>
{
    c.SwaggerDoc("v1", new Info
    {
        Version = "v1",
        Title = "yilezhu's API",
        Description = "A simple example ASP.NET Core Web API",
        TermsOfService = "None",
        Contact = new Contact
        {
            Name = "依樂祝",
            Email = string.Empty,
            Url = "http://www.cnblogs.com/yilezhu/"
        },
        License = new License
        {
            Name = "許可證名字",
            Url = "http://www.cnblogs.com/yilezhu/"
        }
    });
});

　　二、爲接口方法添加註釋

　　（1）爲方法添加註釋；

　　（2）啓用XML 註釋

• 右鍵單擊「解決方案資源管理器」中的項目，而後選擇「屬性」
• 查看「生成」選項卡的「輸出」部分下的「XML 文檔文件」框

　　

　　啓用 XML 註釋後會爲未記錄的公共類型和成員提供調試信息。若是出現不少警告信息  例如，如下消息指示違反警告代碼 1591：

warning CS1591: Missing XML comment for publicly visible type or member 'TodoController.GetAll()'

　　能夠按照下圖所示進行取消：

　　

　　注意上面生成的xml文檔文件的路徑：

　　1.對於 Linux 或非 Windows 操做系統，文件名和路徑區分大小寫。 例如，「SwaggerDemo.xml」文件在 Windows 上有效，但在 CentOS 上無效。

​ 　　2.獲取應用程序路徑，建議採用Path.GetDirectoryName(typeof(Program).Assembly.Location)這種方式或者·AppContext.BaseDirectory這樣來獲取

 

//註冊Swagger生成器，定義一個和多個Swagger 文檔
            services.AddSwaggerGen(c =>
            {
                c.SwaggerDoc("v1", new Info
                {
                    Version = "v1",
                    Title = "yilezhu's API",
                    Description = "A simple example ASP.NET Core Web API",
                    TermsOfService = "None",
                    Contact = new Contact
                    {
                        Name = "依樂祝",
                        Email = string.Empty,
                        Url = "http://www.cnblogs.com/yilezhu/"
                    },
                    License = new License
                    {
                        Name = "許可證名字",
                        Url = "http://www.cnblogs.com/yilezhu/"
                    }
                });
                // 爲 Swagger JSON and UI設置xml文檔註釋路徑
                var basePath = Path.GetDirectoryName(typeof(Program).Assembly.Location);//獲取應用程序所在目錄（絕對，不受工做目錄影響，建議採用此方法獲取路徑）
                var xmlPath = Path.Combine(basePath, "BaseAPI.xml");
                c.IncludeXmlComments(xmlPath);
            });

　　經過上面的操做能夠總結出，Swagger UI 顯示上述註釋代碼的 <summary> 元素的內部文本做爲api大的註釋！

　　固然你還能夠將 remarks 元素添加到 Get 操做方法文檔。 它能夠補充 <summary> 元素中指定的信息，並提供更可靠的 Swagger UI。 <remarks> 元素內容可包含文本、JSON 或 XML。

　　三、描述響應類型

　　接口使用者最關心的就是接口的返回內容和響應類型啦。下面展現一下201和400狀態碼的一個簡單例子：

　　在咱們的方法上添加：[ProducesResponseType(201)][ProducesResponseType(400)]

　　而後添加相應的狀態說明：返回value字符串若是id爲空

/// <summary>
/// 這是一個帶參數的get請求
/// </summary>
/// <remarks>
/// 例子:
/// Get api/Values/1
/// </remarks>
/// <param name="id">主鍵</param>
/// <returns>測試字符串</returns> 
/// <response code="201">返回value字符串</response>
/// <response code="400">若是id爲空</response>  
 // GET api/values/2
[HttpGet("{id}")]
[ProducesResponseType(201)]
[ProducesResponseType(400)]
public ActionResult<string> Get(int id)
{
     return $"你請求的 id 是 {id}";
}

　　效果以下所示