一 為什么使用swaggerswagger是一種API文檔管理的框架 1.可以在代碼中添加注釋，且自動(dòng)生成API文檔，無需再次編寫，友好的界面讓API文檔更易懂。 2.一站式服務(wù)，只需要訪問swagger的地址，就可以看到所有的后臺(tái)接口和功能，并且能測(cè)試接口狀態(tài)，真正是徹底的前后端分離了。 3.內(nèi)嵌調(diào)試，可以查看接口狀態(tài)和返回值結(jié)果很方便。 思考：如果能在把請(qǐng)求日志也集成進(jìn)去就更好了。 二 開始一步一步搭建swagger第一步：創(chuàng)建一個(gè).NET CORE的web項(xiàng)目（vs2019）
到這兒一個(gè).NET core webapi就創(chuàng)建完成了，下面我們進(jìn)行swagger的引用和使用。 第二步：使用Swagger 選擇項(xiàng)目右鍵單擊管理nuget包
打開之后，選擇瀏覽輸入 Swashbuckle.AspNetCore ，選擇后安裝
然后依次點(diǎn)擊確定和接受，就算安裝完成了。安裝完成后，依賴項(xiàng)里面就會(huì)多出來一個(gè)包的引用。
包引入完成后，下一步就是需要注冊(cè)Swagger了，這里我們可以創(chuàng)建一個(gè)類來存放注冊(cè)的信息（代碼會(huì)整潔，邏輯也會(huì)清晰一點(diǎn)），首先新建一個(gè)文件夾名字隨便取，在新建一個(gè)Swagger類。
需要引用 using Microsoft.Extensions.DependencyInjection; using Microsoft.Extensions.DependencyInjection;using Microsoft.OpenApi.Models;using System;using System.Collections.Generic;using System.Linq;using System.Threading.Tasks;namespace WebApi.Core.Api.SetUpService
{ public static class SwaggerSetUp
{ public static void AddSwaggerSetup(this IServiceCollection services)
{ if (services == null) throw new ArgumentNullException(nameof(services)); var ApiName = "Webapi.Core";
services.AddSwaggerGen(c =>
{
c.SwaggerDoc("V1", new OpenApiInfo
{ // {ApiName} 定義成全局變量，方便修改
Version = "V1",
Title = $"{ApiName} 接口文檔——Netcore 3.0",
Description = $"{ApiName} HTTP API V1",
});
c.OrderActionsBy(o => o.RelativePath);
});
}
}
}接下來就是需要到 Startup 類，找到ConfigureServices 注冊(cè)我們寫好的服務(wù)，可以把光標(biāo)放在AddSwaggerSetup按12，就會(huì)跳轉(zhuǎn)到我們寫的SwaggerSetUp方法中。
接著在StartUp類中找到Configure方法編輯，這里面RoutePrefix 就是你需要訪問的url路徑后面的路由比如 我們?cè)L問 localhost:8080/ApiDoc就可以跳轉(zhuǎn)到Swagger的頁面
我們把IIS 啟動(dòng)的注釋，項(xiàng)目啟動(dòng)的Url改成根目錄
修改后按F5啟動(dòng)項(xiàng)目，沒有找到
接下來我們輸入/ApiDoc敲回車，就可以了，這就是配置 RoutePrefix 屬性的作用。
我們找到Startup中的Configure把RoutePrefix 設(shè)置為空再按F5啟動(dòng)，直接根目錄打開就進(jìn)入了Swagger頁面中。
接下來我們實(shí)際使用一下，先把自帶的Controller刪除，然后創(chuàng)建一個(gè)BaseController繼承ControllerBase ，右鍵Controllers選擇添加-控制器，選一個(gè)空的控制器，取名字
BaseController是一個(gè)基類，目的是為了自定義路由，然后放一些公共的方法，這樣你每次新建一個(gè)類就只需要繼承BaseController類無需做太多重復(fù)工作了
接下來我們創(chuàng)建一個(gè)UserController，創(chuàng)建方式如同上面的，把這兩個(gè)地方修改一下
添加代碼 using System;using System.Collections.Generic;using System.Linq;using System.Threading.Tasks;using Microsoft.AspNetCore.Http;using Microsoft.AspNetCore.Mvc;namespace WebApi.Core.Api.Controllers
{ public class UsersController : BaseController
{
[HttpGet] public IActionResult Hello()
{ return Ok("Hello World");
}
}
}F5啟動(dòng)，這樣一個(gè)簡(jiǎn)單的Swagger就已經(jīng)搭建完成。但是比較簡(jiǎn)單，功能也不是很多
下面繼續(xù)在Swagger下面添加一些東西。文檔注釋，我們新建一個(gè)Model類庫，因?yàn)镾wagger不僅可以把接口注釋顯示，也可以對(duì)實(shí)體進(jìn)行注釋的顯示。 右鍵解決方案->添加->新建項(xiàng)目->選擇類庫->創(chuàng)建類庫
右鍵項(xiàng)目->屬性->生成 WebApi.Core.Model 也同樣操作
XML文件放在同一個(gè)位置方便管理
配置好了XML，接下來要關(guān)聯(lián)這個(gè)配置 編輯 SwaggerSetUp.cs類 找到 AddSwaggerSetup函數(shù)，添加XML關(guān)聯(lián)代碼 public static void AddSwaggerSetup(this IServiceCollection services)
{ if (services == null) throw new ArgumentNullException(nameof(services)); var ApiName = "Webapi.Core";
services.AddSwaggerGen(c =>
{
c.SwaggerDoc("V1", new OpenApiInfo
{ // {ApiName} 定義成全局變量，方便修改
Version = "V1",
Title = $"{ApiName} 接口文檔——Netcore 3.0",
Description = $"{ApiName} HTTP API V1",
});
c.OrderActionsBy(o => o.RelativePath); // 獲取xml注釋文件的目錄
var xmlPath = Path.Combine(AppContext.BaseDirectory, "WebApi.Core.Api.xml");
c.IncludeXmlComments(xmlPath, true);//默認(rèn)的第二個(gè)參數(shù)是false，這個(gè)是controller的注釋，記得修改 // 獲取xml注釋文件的目錄
var xmlPathModel = Path.Combine(AppContext.BaseDirectory, "WebApi.Core.Model.xml");
c.IncludeXmlComments(xmlPath, true);//默認(rèn)的第二個(gè)參數(shù)是false，這個(gè)是controller的注釋，記得修改
});
}下面在model類庫中添加一個(gè)類UsersModel 寫好全部的注釋
接下來在UsersController 添加函數(shù)來驗(yàn)證 注釋是否有效
這里我們加了注釋，啟動(dòng)F5 看看效果，從下面的圖片看，是沒問題的注釋已經(jīng)顯示出來了，但是model在哪里，為什么沒有顯示出來
我們?cè)赨sersController 添加如下函數(shù) /// <summary>
/// 用戶實(shí)體類測(cè)試 /// </summary>
/// <param name="usersModel"></param>
/// <returns></returns> [HttpPost] public IActionResult UsersTestSwagger(UsersModel usersModel)
{ return Ok(usersModel);
}然后F5啟動(dòng)，這里我們看到 model類 顯示出來了，但是沒有注釋為什么呢
經(jīng)過排查發(fā)現(xiàn)SwaggerSetUp類中的AddSwaggerSetup 函數(shù)里面有一段代碼寫錯(cuò)了，因?yàn)閺?fù)制粘貼的問題，這種問題我們經(jīng)常會(huì)犯，所以如果可以，以后盡量不要復(fù)制粘貼，還能加深你敲代碼的能力。
改好之后 重新F5 ，已經(jīng)把model類里面的注釋也顯示出來了，
如果我們不想在Swagger 里面顯示出來 那就可以在函數(shù)上面加一個(gè)特性 [ApiExplorerSettings(IgnoreApi = true)]
可以看到 Hello 這個(gè)函數(shù)就被隱藏了
到此，.net core 搭建和使用Swagger就算完成了，是不是很簡(jiǎn)單。 下面在簡(jiǎn)單介紹一下，請(qǐng)求和響應(yīng)應(yīng)該怎么去看
我們單擊try it out
我們編輯好參數(shù)，單擊Execute按鈕，可以看到請(qǐng)求一個(gè)json串，并且把這個(gè)json串原樣輸出了，這在以前需要借助工具來完成，現(xiàn)在直接在啟動(dòng)的程序上就可以查看你的接口寫的是否正確，或者哪里有問題了
|
|
|
