開篇：
現在項目的開發一般都采用前后端分離的模式，后端同學完成開發后需要給前端的同學提供詳細的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.4 api分組管理
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，羅里吧嗦碼了這些，文本粗糙，請多包涵，有問題歡迎指出，謝過！