【 .NET Core 3.0 】框架之三 || swagger的使用
一、為什么使用Swagger
上文中已經(jīng)說到，單純的項目接口在前后端開發(fā)人員使用是特別不舒服的，那所有要推薦一個，既方便又美觀的接口文檔說明框架，當當當，就是Swagger，隨著互聯(lián)網(wǎng)技術的發(fā)展，現(xiàn)在的網(wǎng)站架構基本都由原來的后端渲染，變成了：前端渲染、后端分離的形態(tài)，而且前端技術和后端技術在各自的道路上越走越遠。?
前端和后端的唯一聯(lián)系，變成了API接口；API文檔變成了前后端開發(fā)人員聯(lián)系的紐帶，變得越來越重要，swagger就是一款讓你更好的書寫API文檔的框架。
沒有API文檔工具之前，大家都是手寫API文檔的，在什么地方書寫的都有，有在confluence上寫的，有在對應的項目目錄下readme.md上寫的，每個公司都有每個公司的玩法，無所謂好壞。
書寫API文檔的工具有很多，但是能稱之為“框架”的，估計也只有swagger了。
?
二、配置Swagger服務
1、引用Nuget包
下面開始引入swagger插件
方法有兩個：
1）可以去swagger官網(wǎng)或github上下載源碼，然后將源碼（一個類庫）引入自己的項目；
2）直接利用NuGet包添加程序集應用（這里就是前邊說的 在以后的開發(fā)中，Nuget無處不在）。
右鍵項目中的 Dependencies -- > Manage Nuget Packags --> Browse --> Search "Swashbuckle.AspNetCore" --> Install 5.0以上版本
這里注意下，要勾選上 包含預覽版 ，如果不勾選，只能看到4.0版本，畢竟5.0還沒有正式發(fā)布。
?
?
然后就在項目的Nuget依賴包 Packages 里看到剛剛引入的Swagger包
?
這個時候，你可以試運行一下，當然是不可以的，因為我們還沒有配置。
?
2、配置服務
打開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"); //路徑配置，設置為空，表示直接在根域名（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中間件的時候，把啟動地址設置了空，就是這里
所以這個時候，我們是直接訪問域名根目錄就行了，比如 localhost://8081即可。
還有一個小問題就是，因為我們的項目，官方默認的是 /WeatherForecast地址，所以我們需要修改一下，在 launchSettings.json 文件中的 launchUrl設置為空，或者刪掉就行。
這個時候我們直接訪問項目根目錄，當當當出來了：
?
5、好像少點兒什么？！
?
在上邊的截圖中，我們可以看到，已經(jīng)生成了一個 api 列表，我們不僅可以清晰的看到項目中含有那些接口，還可以直接點擊發(fā)送請求，類似 postman 那樣，做接口調(diào)試，
但是現(xiàn)在有兩個問題：
1、這個接口文檔現(xiàn)在還不多，如果多了的話，每個接口對應的意義可能會混淆，
2、另外，這個接口文檔，也是方便前端工程師查看的，目前這個這個樣式，看起來是挺費解的。
?
這個時候，要是有一個注釋功能就很好了，別著急，看看下邊的截圖，是不是你想要的效果？！
?
既美觀又快捷，而且還有豐富的注釋，這樣以后發(fā)布出去，前后端開發(fā)人員就可以一起開發(fā)了，嗯！不錯！
那這個注釋功能，應該這么做呢？別著急馬上開始。
三、swagger文檔完善
1、為接口添加注釋
接下來，我們就需要解決第二個問題，如何增加文字說明，就是傳說中的注釋：
右鍵項目名稱=>屬性=>生成，勾選“輸出”下面的“xml文檔文件”，系統(tǒng)會默認生成一個，當然老規(guī)矩，你也可以自己起一個名字：
這里我用的是相對路徑，可以直接生成到 api 層的 bin文件夾下
?
?
?
這個時候，先別忙著運行項目，作為老司機的我，只要是改代碼或者配置文件，保存后，第一件事就是看看有沒有錯誤，一看，咦~~~果然，雖然是警告，可以強迫癥呀，一看還挺多
?
別慌！一看，哦！原來是swagger把一些接口方法都通過xml文件配置了，就是剛剛上文提到的，所以我們只需要加上方法注釋就可以辣，可以左斜杠/，連續(xù)三下即可
?
如果你不想每一個方法都這么加注釋，可以這么配置（對當前項目進行配置，可以忽略警告，記得在后邊加上分號 ;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、當前 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)金大獎總結
以上是生活随笔為你收集整理的【 .NET Core 3.0 】框架之三 || swagger的使用的全部內(nèi)容，希望文章能夠幫你解決所遇到的問題。
- 上一篇： asp.net core 3.0 更新简
- 下一篇： asp.net ajax控件工具集 Au