swagger是什么？

Swagger 是一個規范和完整的框架，用于生成、描述、調用和可視化 RESTful 風格的 Web 服務?？傮w目標是使客戶端和文件系統作為服務器以同樣的速度來更新。文件的方法，參數和模型緊密集成到服務器端的代碼，允許API來始終保持同步。

swagger作用 

  (1)接口的文檔在線自動生成。 
  (2)功能測試。

接口開發的痛點

相信無論是前端還是后端開發，都或多或少地被接口文檔折磨過。前端經常抱怨后端給的接口文檔與實際情況不一致。后端又覺得編寫及維護接口文檔會耗費不少精力，經常來不及更新。其實無論是前端調用后端，還是后端調用后端，都期望有一個好的接口文檔。但是這個接口文檔對于程序員來說，就跟注釋一樣，經常會抱怨別人寫的代碼沒有寫注釋，然而自己寫起代碼起來，最討厭的，也是寫注釋。所以僅僅只通過強制來規范大家是不夠的，隨著時間推移，版本迭代，接口文檔往往很容易就跟不上代碼了。
 
但即便如此，對于許多開發來說，編寫這個yml或json格式的描述文件，本身也是有一定負擔的工作，特別是在后面持續迭代開發的時候，往往會忽略更新這個描述文件，直接更改代碼。久而久之，這個描述文件也和實際項目漸行漸遠，基于該描述文件生成的接口文檔也失去了參考意義。所以再Java屆服務端的大一統框架Spring，迅速將Swagger規范納入自身的標準，建立了Spring-swagger項目，后面改成了現在的Springfox。通過在項目中引入Springfox，可以掃描相關的代碼，生成該描述文件，進而生成與代碼一致的接口文檔和客戶端代碼。而.Net生態，自從webapi2.0開始便開始使用Swagger作為接口文檔，到.NetCore生化后，Swagger更是普通使用的接口文檔規范，最常使用的組件就是Swashbuckle.AspNetCore。
這種通過代碼生成接口文檔的形式，在后面需求持續迭代的項目中，顯得尤為重要和高效。

.NetCore3.1中如何使用Swagger呢？

第一步：引入Swagger

用Vs2019創建.NetCore3.1的WebApi項目后，在VS2019里依次點擊  “工具”-“NuGet包管理器(N)”-"管理解決方案的NuGet程序包(N)",打開后，搜索“Swashbuckle.AspNetCore”，選擇最新版（目前最新版本為5.0.0），解決方案的項目列表里勾選WebApi項目，其他的項目（比如Domain,Common,Infrastructure）不需要勾選。點擊“安裝即可”。

第二步：Startup配置

1、ConfigureServices方法里將Swagger加入到容器IServiceCollection里，，并且指定讀取站點目錄下所有的xml文件，代碼如下：

 services.AddSwaggerGen(c =>
{
 c.SwaggerDoc("v1", new OpenApiInfo { Version = "v1", Title = "zyiz.net系統WebApi" });
                 
                var dir = new DirectoryInfo(AppContext.BaseDirectory);
                foreach (FileInfo file in dir.EnumerateFiles("*.xml"))
                {
                    c.IncludeXmlComments(file.FullName);
                }
            });

2、Configure方法里開啟SwaggerUI，代碼如下：

 app.UseSwagger().UseSwaggerUI(c => { c.SwaggerEndpoint("/swagger/v1/swagger.json", "MuXue.Zyiz.net API V1"); });

第三步：設置并且生成xml文件

1、解決方案-WebApi項目名右擊---“屬性”，點“生成”，界面下方，“輸出”部分，勾選“XML文檔文件(X)”,可以看到生成的路徑為絕對路徑，可以改為相對路徑，類似這樣，加2個點好，然后是WebApi項目目錄名，后面的xml文件名不變。

..\MuXue.Zyiz.Template.WebApi\MuXue.Zyiz.Template.WebApi.xml

2、項目一般會有Model的實體層，配置跟上面類似，

..\MuXue.Zyiz.Template.Domain\MuXue.Zyiz.Template.Domain.xml

第4步：生成解決方案，F5啟動即可。

有人發現，本地的swagger有字段說明，但是發布到服務器上，就沒有字段說明，原因是.netcore 3.1發布后，不會生成xml文件。解決方方法是，在vs2019項目里，剛剛我們設置成功生成的2個xml文件，右擊-“屬性”-“復制到輸出目錄”設置為“始終復制”即可。