開篇：

　　現在專案的開發一般都採用前後端分離的模式，後端同學完成開發後需要給前端的同學提供詳細的API介面文件說明，手動整理費事費力。那有沒有解放雙手的自動化工具呢？答案是肯定的。之前做.net webapi的時候使用的HelpPage來生成的API文件，到netcore這裡，就是我們今天要分享的Swagger，它可以根據程式碼註釋自動生成API描述文件，也可以通過配置生成互動式文件實現線上介面測試。

關於這個swagger大兄弟：

　　全稱：Swashbuckle.AspNetCore，開源專案，git地址：https://github.com/domaindrivendev/Swashbuckle.AspNetCore

目錄：

　　1.基本使用

　　　　1.1 安裝依賴

　　　　1.2 startup配置

　　　　1.3 swagger啟動配置

　　2.進階使用

　　　　2.1 介面描述

　　　　2.2 返回型別描述

　　　　2.3忽略不生成到API文件

　　　　2.4api分組管理

　　　　2.5多xml文件配置

　　3.擴充套件使用

　　　　3.1 全域性資訊新增（作者、聯絡人、許可資訊等）

　　　　3.2 預設摺疊配置

一、基本使用

　　1.1 安裝Swagger依賴

　　第一種方式，程式包管理控制檯：install-package Swashbuckle.AspNetCore

　　第二種方式，Nuget包管理中搜索Swashbuckle.AspNetCore

　　1.2 startup配置

　　要使用swagger生成文件，我們需要在startup的ConfigureServices 和Configure中對其進行中介軟體配置

• 在ConfigureServices中註冊swagger生成器

1 // 註冊swagger生成器，定義一個或多個文件，多個文件後邊會講到
2 services.AddSwaggerGen(c =>
3 {
4     c.SwaggerDoc("v1", new OpenApiInfo { Title = "曦昊-API說明文件", Version = "v1" });
5 });

• 在Configure中啟用中介軟體配置

 // 啟用中介軟體以將生成的 Swagger 公開為JSON終結點
 app.UseSwagger();
 // 啟用swagger-ui 中介軟體，指定 Swagger JSON 終結點，以來公開互動式文件
 app.UseSwaggerUI(c =>
 {
    c.SwaggerEndpoint("/swagger/v1/swagger.json", "API說明文件 V1");
 });

　　至此，swagger的基本配置完成，我們可以啟動應用程式，輸入/swagger訪問看看啦

　　我們可以看到swagger已經自動幫我們生成了專案的api介面描述文件

　　1.3 swagger啟動配置

　　完成上邊的步驟後，我們已經可以啟動瀏覽/swagger訪問我們的Rest Apis文件了，但是每次啟動再輸入swagger也太麻煩了，接下來我們把swagger設定為我們的啟動地址

　　檔案：Properties - >launchSettings.json

　　將標註位置改為“swagger”

　　再次啟動，直接進入了我們的swagger文件頁面。

二、進階使用

　　2.1 介面描述

　　上邊已經提過swagger會根據我們的註釋生成文件描述資訊，但並不是我們添加了註釋就可以的，想要swagger正常顯示我們的備註資訊，除了添加註釋資訊外，我們還要為swagger配置包含xml描述資訊

　　首先按照我們平常的註釋方式為介面添加註釋

　　其次，為我們的專案配置輸出xml檔案（專案右鍵--屬性--生成--輸出）

　　最後在startup的ConfigureServices中配置swagger包含xml描述資訊

    // 配置從xml文件中獲取描述資訊
    // 路徑我們獲取的專案路徑+startup名稱空間（也可以直接寫生成的xml名稱）
    var filePath = Path.Combine(System.AppContext.BaseDirectory, typeof(Startup).Assembly.GetName().Name + ".xml");
    c.IncludeXmlComments(filePath);

　　ok，現在我們啟動除錯進入swaggerUI，我們會看到swagger已經顯示出了我們自定義的註釋資訊

　　2.2 返回型別描述

　　當我們寫的介面已IActionResult為返回型別的時候，我們會發現swagger的Responses下並沒有為我們生成返回資訊描述，因為它並不知道我們具體要返回的是什麼形式的資料

　　例如，我們新寫一個分頁介面：

　　我們可以看到沒有任何的返回資訊描述，那怎麼辦呢？這裡我們就要用到swagger的ProducesResponseType特性來告訴swagger我們的返回結構

　　再次啟動除錯，我們發現在Responses這一模組已經正確顯示了我們的PageList描述資訊。

　　細心的可能會發現我們在使用ProducesResponseType的時候除了給了它一個type，還給了一個200，這是啥意思呢？

　　這個200的意思就是響應狀態200的時候我給你返回這麼一個結構的資料，那是不是說我們可以定義不同響應狀態不同資料結構呢？答案是肯定的。ProducesResponseType是可以多次標記的，你只需要為其他狀態按照上邊的方式新增返回結構標記即可

　　2.3忽略不生成到API文件

　　有些時候我們需要向文件的閱讀者隱藏部分的介面資訊，這個時候我們就會用到ApiExplorerSettings特性

　　在我們需要隱藏的介面標記 [ApiExplorerSettings(IgnoreApi = true)] 即可

　　2.4 api分組管理

　　當我們的介面過多想要拆分顯示，或我們根據不同大類進行區分（系統操作、業務操作...），或我們要分多個版本等等，我們就需要用到分組這個操作，實際上分組就是為swagger生成多個文件，上操作：

　　第一步，為swagger新增一個新的文件（startup -- > ConfigureServices）

　 第二步，為swagger新增一個對應的json終結點

　　第三步，為控制器或action方法新增標記[ApiExplorerSettings(GroupName = "v2")] ，groupName設定的是要在哪一組中顯示，這裡是區分大小寫的，要跟上述設定中保持一致

　　 然後就可以在swagegrUI介面的右上角切換不同的文件了

　　2.5 多xml文件配置

　　常用場景：跨程式集顯示註釋資訊

　　swagger我們預設配置的是載入當前程式生成的xml，我們只需要為為其它程式集配置輸出xml，並在services.AddSwaggerGen中配置載入改xml檔案即可

　　例如：

　 但是，如果有多個程式集需要配置，這裡是不是會有很多的配置項，並且每加一個程式集我們就要寫一遍，即不方便又造成程式碼的臃腫。ok，接下來我們進行一下改版

　　首先，我們把所有的xml生成到一個目錄下，比如當前應用根目錄的docs:

　　然後我們在swagger設定xml文件的地方改為以下方式　　

    // 獲取自定義的xml目錄   
    var xmlPath = Path.Combine(System.AppContext.BaseDirectory, "Docs");
    DirectoryInfo dir = new DirectoryInfo(xmlPath);
    // 獲取目錄下的所有xml檔案，並設定為swagger文件包含檔案
    dir.GetFiles("*.xml").ToList().ForEach(u =>
    {
         c.IncludeXmlComments(u.FullName, true);
    })

　　ok，再次啟動程式，我們會發現，XH.Core下Model物件的描述資訊也有了~

三、擴充套件使用

　　3.1全域性資訊新增（作者、聯絡人、許可資訊等）

　　這些資訊的配置是在services.AddSwaggerGen下進行配置，如下：

　　執行程式，顯示如下

　　3.2 預設摺疊配置

　　當介面慢慢變多，你想進入swagger頁面後能非常清晰的瀏覽controller級目錄，你會需要這個配置　　

    app.UseSwaggerUI(c =>
    {
         c.SwaggerEndpoint("/swagger/v1/swagger.json", "API說明文件 V1");
         c.SwaggerEndpoint("/swagger/v2/swagger.json", "API說明文件 V2");
         c.DocExpansion(DocExpansion.None); // 全部摺疊
    });

　　如果想隱藏掉Schemas,使用c.DefaultModelsExpandDepth(-1) 設定即可，位置同上

　　ok，羅裡吧嗦碼了這些，文字粗糙，請多包涵，有問題歡迎指出，謝過！