asp.net core系列 37 WebAPI 使用OpenAPI (swagger)中間件

一.概述

　　在使用Web API時，對於開發人員來講，瞭解其各類方法多是一項挑戰。在ASP.NET Core上，Web api 輔助工具介紹二箇中間件，包括：Swashbuckle和NSwag .NET。本篇先講Swashbuckle。兩者都使用Swagger規範，Swagger也稱爲OpenAPI，解決了爲Web API生成有用文檔和幫助頁面的問題。它提供了諸如交互式文檔，客戶端SDK生成和API可發現性等好處。

　　(1) Swashbuckle.AspNetCore是一個開源項目，用於爲ASP.NET Core Web API生成Swagger文檔。

　　(2) NSwag是另外一個開源項目，該項目將Swashbuckle和AutoRest（客戶端生成）的功能集成在一個工具鏈中。用於生成Swagger文檔並將Swagger UI或ReDoc集成到ASP.NET Core Web API中。此外，NSwag還提供了爲API生成C＃和TypeScript客戶端代碼的方法。

　　

　　1.1 什麼是Swagger / OpenAPI

　　　　Swagger是一種與開發語言無關的規範，用於描述REST API。Swagger項目被捐贈給OpenAPI計劃，如今稱爲OpenAPI。兩個名稱可互換使用; 可是，OpenAPI是首選。它容許計算機和IT人理解服務的功能，而無需直接訪問實現（源代碼，網絡訪問，文檔）。一個目標是最小化鏈接不相關服務所需的工做量。另外一個目標是減小準確記錄服務所需的時間。

 

　　1.2  Swagger規範（swagger.json）

　　　　Swagger流程的核心是Swagger規範，默認狀況下是一個名爲swagger.json的文檔。它由Swagger工具鏈（或其第三方實現）根據你的服務生成。它描述了 API 的功能以及使用 HTTP 對其進行訪問的方式。 它驅動 Swagger UI，並由工具鏈用來啓用發現和客戶端代碼生成。

 

　　1.3 Swagger UI

　　　　Swagger UI 提供了基於 Web 的 UI，它使用生成的 Swagger 規範提供有關服務的信息。 Swashbuckle 和 NSwag 均包含 Swagger UI 的嵌入式版本，所以可以使用中間件註冊調用將該嵌入式版本託管在 ASP.NET Core 應用中。

 

二.  添加 Swashbuckle中間件

　　關於Swashbuckle有三個主要組成部分：

　　(1) Swashbuckle.AspNetCore.Swagger： 一個Swagger對象模型和中間件，用於將SwaggerDocument對象公開爲JSON端點。

　　(2) Swashbuckle.AspNetCore.SwaggerGen：一個Swagger生成器，可SwaggerDocument直接從路由，控制器和模型構建對象。它一般與Swagger端點中間件結合使用，以自動顯示Swagger JSON。

　　(3) Swashbuckle.AspNetCore.SwaggerUI： Swagger UI工具的嵌入式版本。它解釋 Swagger JSON 以構建描述 Web API 功能的可自定義的豐富體驗。它包括用於公共方法的內置測試工具。

　　

　　 2.1 包安裝

　　　　經過vs 2017的程序包管理器控制檯，運行安裝Install-Package Swashbuckle.AspNetCore -Version 5.0.0-beta。 安裝信息以下所示：

 

　　2.2  配置Swagger中間件

　　　　將 Swagger 生成器添加到 Startup.ConfigureServices 方法中的服務集合中

            //將SwaggerGen服務添加到服務集合中， OpenApiInfo是它的自帶類。
            services.AddSwaggerGen(c =>
            {
                //注意不能用大寫V1，否則老報錯，Not Found /swagger/v1/swagger.json
                c.SwaggerDoc("v1", new OpenApiInfo { Title = "My API", Version = "v1" });
            });

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

public void Configure(IApplicationBuilder app)
{
    //...
     
    // Enable middleware to serve generated Swagger as a JSON endpoint.
    app.UseSwagger();

    // Enable middleware to serve swagger-ui (HTML, JS, CSS, etc.), 
    // specifying the Swagger JSON endpoint.
    // UseSwaggerUI方法調用啓用靜態文件中間件。
    app.UseSwaggerUI(c=> {
                c.SwaggerEndpoint("/swagger/v1/swagger.json", "My API V1");
            });

    app.UseMvc();
}

 　　　　啓動應用，並導航到 http://localhost:<port>/swagger/index.html下，查看Web API生成Swagger文檔以下所示(一個網頁，二處截圖拼在一塊兒)：

 

三.自定義和擴展

　　Swagger 提供了爲對象模型進行歸檔和自定義 UI 以匹配你的主題的選項。

　　

　　3.1 API 信息和說明的配置

　　　　能夠在AddSwaggerGen方法中配置，添加諸如做者，許可證和描述之類的信息，經過OpenApiInfo類來添加。

            services.AddSwaggerGen(c =>
            {
                //注意不能用大寫V1，否則老報錯，Not Found /swagger/v1/swagger.json
                c.SwaggerDoc("v1", new OpenApiInfo{
                    Version = "v1",
                    Title = "ToDo API",
                    //服務描述
                    Description = "A simple example ASP.NET Core Web API",
                    //API服務條款的URL
                    TermsOfService = new Uri("http://tempuri.org/terms"),
                    Contact = new OpenApiContact
                    {
                        Name = "Joe Developer",
                        Email = "joe.developer@tempuri.org"
                    },
                    License = new OpenApiLicense
                    {
                        Name = "Apache 2.0",
                        Url = new Uri("http://www.apache.org/licenses/LICENSE-2.0.html")
                    }
                });
            });

　　　　Swagger UI 顯示版本的信息：

 

　　3.2 XML註釋api

　　　　在「解決方案資源管理器」中右鍵單擊該項目，而後選擇「編輯 <project_name>.csproj」。 手動添加如下代碼到 .csproj 文件中。

    <PropertyGroup>
      <GenerateDocumentationFile>true</GenerateDocumentationFile>
      <NoWarn>$(NoWarn);1591</NoWarn>
    </PropertyGroup>

　　　　接下來配置 Swagger 以使用生成的 XML 文件。對於 Linux 操做系統，文件名和路徑區分大小寫。例如，「TodoApi.XML」文件在 Windows 上有效，但在 CentOS 上無效。配置和解決以下所示：

    services.AddSwaggerGen(c =>
    {
        //...配置SwaggerDoc 省略
        // Set the comments path for the Swagger JSON and UI.
        var xmlFile = $"{Assembly.GetExecutingAssembly().GetName().Name}.xml";
        var xmlPath = Path.Combine(AppContext.BaseDirectory, xmlFile);
        c.IncludeXmlComments(xmlPath);
    });

　　　　接着對每一個api方法添加操做說明註釋，以刪除api來描述以下所示：

        /// <summary>
        /// 刪除一個TodoItem
        /// </summary>
        /// <remarks>
        ///  Sample request:
        ///  DELETE: api/Todo/2
        /// </remarks>
        /// <param name="id"></param>
        /// <returns>不返回內容</returns>
        /// <response code="204">刪除成功，不返回內容</response>
        /// <response code="404">刪除失敗，未找到該記錄</response>
        [HttpDelete("{id}", Name = "DeleteTodoItem")]
        [ProducesResponseType(204)]
        [ProducesResponseType(404)]
        public async Task<IActionResult> DeleteTodoItem(long id)
        {
            var todoitem = await _context.TodoItems.FindAsync(id);
            if (todoitem == null)
            {
                return NotFound();
            }

            _context.TodoItems.Remove(todoitem);
            await _context.SaveChangesAsync();

            return NoContent();
        }

　　　　啓動程序後，Swagger UI 顯示的Delete刪除api的描述以下圖。還能夠點擊try it out按鈕進行測試刪除，圖中顯示server response 返回204刪除成功。

　　

　　3.2 數據註釋

　　　　使用 System.ComponentModel.DataAnnotations 命名空間中的屬性來修飾模型，以幫助驅動 Swagger UI 組件。下面將 [Required] 屬性添加到 TodoItem 類的 Name 屬性：

         [Required]
        public string Name { get; set; }

　　　　此屬性的狀態更改 UI 行爲並更改基礎 JSON 架構：

　　　　　　

　　　　將 [Produces("application/json")] 屬性添加到 API 控制器。 這樣作的目的是聲明控制器的操做支持 application/json 的響應內容類型：

[Produces("application/json")]
[Route("api/[controller]")]
[ApiController]
public class TodoController : ControllerBase
{
   //..
}

 　　　　　　

　　

　　　　最後還能夠自定義Swagger UI，這裏不在演示，能夠查看官網。更多功能介紹上github。

 

　　注意： 當把swagger集成到asp.net core webapi項目中，在vs 2009中以IIS Express來運行/swagger/index.html 一直報404錯誤,但發佈到IIS服務器上卻運行正常。解決方法:嘗試刪除項目中的隱藏文件.vs,刪除後運行項目會再自動生成.vs文件，以下圖所示：

 

 

 

 

　　參考文獻：

　　　　Swashbuckle 和 ASP.NET Core 入門

　　　　github