---

一、為什么使用Swagger

上文中已經(jīng)說到，單純的項目接口在前后端開發(fā)人員使用是特別不舒服的，那所有要推薦一個，既方便又美觀的接口文檔說明框架，當(dāng)當(dāng)當(dāng)，就是Swagger，隨著互聯(lián)網(wǎng)技術(shù)的發(fā)展，現(xiàn)在的網(wǎng)站架構(gòu)基本都由原來的后端渲染，變成了：前端渲染、后端分離的形態(tài)，而且前端技術(shù)和后端技術(shù)在各自的道路上越走越遠。?

前端和后端的唯一聯(lián)系，變成了API接口；API文檔變成了前后端開發(fā)人員聯(lián)系的紐帶，變得越來越重要，swagger就是一款讓你更好的書寫API文檔的框架。

沒有API文檔工具之前，大家都是手寫API文檔的，在什么地方書寫的都有，有在confluence上寫的，有在對應(yīng)的項目目錄下readme.md上寫的，每個公司都有每個公司的玩法，無所謂好壞。

書寫API文檔的工具有很多，但是能稱之為“框架”的，估計也只有swagger了。

?

二、配置Swagger服務(wù)

1、引用Nuget包

下面開始引入swagger插件

方法有兩個：

1）可以去swagger官網(wǎng)或github上下載源碼，然后將源碼（一個類庫）引入自己的項目；

2）直接利用NuGet包添加程序集應(yīng)用（這里就是前邊說的 在以后的開發(fā)中，Nuget無處不在）。

右鍵項目中的 Dependencies -- > Manage Nuget Packags --> Browse --> Search "Swashbuckle.AspNetCore" --> Install 5.0以上版本

這里注意下，要勾選上 包含預(yù)覽版 ，如果不勾選，只能看到4.0版本，畢竟5.0還沒有正式發(fā)布。

?

?

然后就在項目的Nuget依賴包 Packages 里看到剛剛引入的Swagger包

?

這個時候，你可以試運行一下，當(dāng)然是不可以的，因為我們還沒有配置。

?

2、配置服務(wù)

打開Startup.cs類，編輯 ConfigureServices 類

public string ApiName { get; set; } = "Blog.Core"; var basePath = Microsoft.DotNet.PlatformAbstractions.ApplicationEnvironment.ApplicationBasePath; services.AddSwaggerGen(c => { c.SwaggerDoc("V1", new OpenApiInfo { // {ApiName} 定義成全局變量，方便修改 Version = "V1", Title = $"{ApiName} 接口文檔——Netcore 3.0", Description = $"{ApiName} HTTP API V1", Contact = new OpenApiContact { Name = ApiName, Email = "Blog.Core@xxx.com", Url = new Uri("https://www.jianshu.com/u/94102b59cc2a") }, License = new OpenApiLicense { Name = ApiName, Url = new Uri("https://www.jianshu.com/u/94102b59cc2a") } }); c.OrderActionsBy(o => o.RelativePath); });

?

3、啟動Http中間件

編輯Configure類

// This method gets called by the runtime. Use this method to configure the HTTP request pipeline. public void Configure(IApplicationBuilder app, IWebHostEnvironment env) { if (env.IsDevelopment()) { app.UseDeveloperExceptionPage(); } app.UseSwagger(); app.UseSwaggerUI(c => { c.SwaggerEndpoint($"/swagger/V1/swagger.json", $"{ApiName} V1"); //路徑配置，設(shè)置為空，表示直接在根域名（localhost:8001）訪問該文件,注意localhost:8001/swagger是訪問不到的，去launchSettings.json把launchUrl去掉，如果你想換一個路徑，直接寫名字即可，比如直接寫c.RoutePrefix = "doc"; c.RoutePrefix = ""; }); app.UseRouting(); app.UseAuthorization(); app.UseEndpoints(endpoints => { endpoints.MapControllers(); }); }

?

4、查看效果

到這，已經(jīng)完成swagger的添加，F5 運行調(diào)試，因為我們在上邊配置swagger中間件的時候，把啟動地址設(shè)置了空，就是這里

所以這個時候，我們是直接訪問域名根目錄就行了，比如 localhost://8081即可。

還有一個小問題就是，因為我們的項目，官方默認的是 /WeatherForecast地址，所以我們需要修改一下，在 launchSettings.json 文件中的 launchUrl設(shè)置為空，或者刪掉就行。

這個時候我們直接訪問項目根目錄，當(dāng)當(dāng)當(dāng)出來了：

?

5、好像少點兒什么？！

?

在上邊的截圖中，我們可以看到，已經(jīng)生成了一個 api 列表，我們不僅可以清晰的看到項目中含有那些接口，還可以直接點擊發(fā)送請求，類似 postman 那樣，做接口調(diào)試，

但是現(xiàn)在有兩個問題：

1、這個接口文檔現(xiàn)在還不多，如果多了的話，每個接口對應(yīng)的意義可能會混淆，

2、另外，這個接口文檔，也是方便前端工程師查看的，目前這個這個樣式，看起來是挺費解的。

?

這個時候，要是有一個注釋功能就很好了，別著急，看看下邊的截圖，是不是你想要的效果？！

?

既美觀又快捷，而且還有豐富的注釋，這樣以后發(fā)布出去，前后端開發(fā)人員就可以一起開發(fā)了，嗯！不錯！

那這個注釋功能，應(yīng)該這么做呢？別著急馬上開始。

三、swagger文檔完善

1、為接口添加注釋

接下來，我們就需要解決第二個問題，如何增加文字說明，就是傳說中的注釋：

右鍵項目名稱=>屬性=>生成，勾選“輸出”下面的“xml文檔文件”，系統(tǒng)會默認生成一個，當(dāng)然老規(guī)矩，你也可以自己起一個名字：

這里我用的是相對路徑，可以直接生成到 api 層的 bin文件夾下

?

?

?

這個時候，先別忙著運行項目，作為老司機的我，只要是改代碼或者配置文件，保存后，第一件事就是看看有沒有錯誤，一看，咦~~~果然，雖然是警告，可以強迫癥呀，一看還挺多

?

別慌！一看，哦！原來是swagger把一些接口方法都通過xml文件配置了，就是剛剛上文提到的，所以我們只需要加上方法注釋就可以辣，可以左斜杠/，連續(xù)三下即可

?

如果你不想每一個方法都這么加注釋，可以這么配置（對當(dāng)前項目進行配置，可以忽略警告，記得在后邊加上分號 ;1591）：

?

?

現(xiàn)在呢，配置好了xml文件，接下來需要讓系統(tǒng)啟動的時候，去讀取這個文件了，重新編輯Startup.cs，修改ConfigureServices函數(shù)：

var basePath = Microsoft.DotNet.PlatformAbstractions.ApplicationEnvironment.ApplicationBasePath; services.AddSwaggerGen(c => { c.SwaggerDoc("V1", new OpenApiInfo { // {ApiName} 定義成全局變量，方便修改 Version = "V1", Title = $"{ApiName} 接口文檔——Netcore 3.0", Description = $"{ApiName} HTTP API V1", Contact = new OpenApiContact { Name = ApiName, Email = "Blog.Core@xxx.com", Url = new Uri("https://www.jianshu.com/u/94102b59cc2a") }, License = new OpenApiLicense { Name = ApiName, Url = new Uri("https://www.jianshu.com/u/94102b59cc2a") } }); c.OrderActionsBy(o => o.RelativePath); //就是這里！！！！！！！！！ var xmlPath = Path.Combine(basePath, "blog.core.test3.0.xml");//這個就是剛剛配置的xml文件名 c.IncludeXmlComments(xmlPath, true);//默認的第二個參數(shù)是false，這個是controller的注釋，記得修改 });

然后F5 運行，都加上了，感覺前端大佬再也不會說看不懂接口了，哈哈哈哈

?

3、對 Model 也添加注釋說明

接下來開始第三個問題：添加實體類說明注釋：

?

新建一個.net core 類庫Blog.Core.Model，注意是 .net core的類庫，或者使用標準庫也是可以的！（標準庫可以在 NetCore 和 Framework 兩個項目都可以跑）

?

?

新建一個Love的實體類

/// <summary> /// 這是愛 /// </summary> public class Love { /// <summary> /// id /// </summary> public int Id { get; set; } /// <summary> /// 姓名 /// </summary> public string Name { get; set; } /// <summary> /// 年齡 /// </summary> public int Age { get; set; } }

?

這里現(xiàn)在有兩個情況，或者說是兩個操作方案：

?

1、當(dāng)前 api 層直接引用了 Blog.Core.Model 層；

?

這個時候，我們只需要配置仿照上邊 api 層配置的xml文檔那樣，在 Blog.Core.Model 層的 XML 輸出到 API 層就行了：

?

2、API 層沒有直接引用 Model 層，而是通過級聯(lián)的形式；

就比如我的 Github 上的代碼那樣：

?效果和上邊是一樣的，也算是引用 Model 層了。

?

?

4、改寫注入方法，并在控制器中參數(shù)引用

配置xml文檔，在 startup.cs 的 configureService 方法里

//就是這里 var xmlPath = Path.Combine(basePath, "Blog.Core.xml");//這個就是剛剛配置的xml文件名 c.IncludeXmlComments(xmlPath, true);//默認的第二個參數(shù)是false，這個是controller的注釋，記得修改 var xmlModelPath = Path.Combine(basePath, "Blog.Core.Model.xml");//這個就是Model層的xml文件名 c.IncludeXmlComments(xmlModelPath);

?

?

接口添加注釋

　　　/// <summary> /// post /// </summary> /// <param name="love">model實體類參數(shù)</param> [HttpPost] public void Post(Love love) { }

?

dang dang dang，就出來了

?

?

?

5、去掉Swagger警告提示

在Model層中，我們建立了很多實體，如果你沒有為每一個實體都添加注釋的話，可能會出現(xiàn)這樣的警告：

如果有的小伙伴，不想添加注釋，而又不想看到這個強迫癥的警告提示，那就可以這么做，

右鍵項目 屬性 -》 Errors and warnings 配置 1591：

?

?

6、隱藏某些接口

如果不想顯示某些接口，直接在controller 上，或者action 上，增加特性

? [ApiExplorerSettings(IgnoreApi = true)]

?

?

?或者直接對這個方法 private，也可以直接使用obsolete屬性

四、Github && Gitee

https://github.com/anjoy8/Blog.Core.git

https://gitee.com/laozhangIsPhi/Blog.Core

創(chuàng)作挑戰(zhàn)賽新人創(chuàng)作獎勵來咯，堅持創(chuàng)作打卡瓜分現(xiàn)金大獎

總結(jié)

以上是生活随笔為你收集整理的【 .NET Core 3.0 】框架之三 || swagger的使用的全部內(nèi)容，希望文章能夠幫你解決所遇到的問題。

如果覺得生活随笔網(wǎng)站內(nèi)容還不錯，歡迎將生活随笔推薦給好友。