使用Swashbuckle构建RESTful风格文档
本次和大家分享的是Swagger to WebApi的nuget包Swashbuckle；因?yàn)轫?xiàng)目需要統(tǒng)一api文檔的風(fēng)格，并要支持多種開(kāi)發(fā)語(yǔ)言（C#，java，python），所以首先想到的是swagger來(lái)構(gòu)建api文檔，本章講解的是對(duì).net的webpi來(lái)生成文檔，后續(xù)會(huì)將java的springmvc+swagger來(lái)構(gòu)建接口文檔。
準(zhǔn)備工作
快速構(gòu)建簡(jiǎn)易api文檔
swagger文檔支持在header中增加Token參數(shù)
.?準(zhǔn)備工作
首先創(chuàng)webapi項(xiàng)目，然后通過(guò)nuget管理器安裝Swashbuckle的包，我這里通過(guò)console命令安裝：
?Install-Package Swashbuckle -Version?5.6.0?
注意只需要安裝這個(gè)包就行了，其他的會(huì)自動(dòng)引用，由于Swashbuckle包含了swagger的引用，所以不用再單獨(dú)操作引用了。
.?快速構(gòu)建簡(jiǎn)易api文檔
如上安裝完Swashbuckle后其實(shí)就能夠直接運(yùn)行看效果了，我這里的訪問(wèn)路徑是：?http://localhost:51847/swagger/ui/index?，注意：/swagger/ui/index?是默認(rèn)固定的路徑，這是nuget包封裝的路徑，訪問(wèn)后能看到如下界面效果：
一個(gè)簡(jiǎn)易的文檔就弄好了，swagger的顏色看起來(lái)搭配不錯(cuò)；由于大多數(shù)接口都是post請(qǐng)求方式，因此咋們以/api/values的post接口為例如：
對(duì)于接口文檔而言，上面文檔存在如下一些疏漏：
未說(shuō)明方法的功能
參數(shù)屬性的描述沒(méi)有
返回屬性的描述沒(méi)有
為了方便其他人員對(duì)接接口，所以對(duì)接口文檔我們需要增加一些描述，要增加描述這里就要知曉：Swashbuckle是通過(guò)xml文件來(lái)讀取配置信息的，該xml文件里面包含了我們?cè)诖a中對(duì)方法，對(duì)類(lèi)，對(duì)參數(shù)，對(duì)返回值做的文字描述；首先定義一個(gè)請(qǐng)求和響應(yīng)的實(shí)體?如：
/// <summary>
? ? /// 登錄請(qǐng)求
? ? /// </summary>
? ? public class MoLoginRq
? ? {
? ? ? ? /// <summary>
? ? ? ? /// 賬號(hào)
? ? ? ? /// </summary>
? ? ? ? public string UserName { get; set; }
? ? ? ? /// <summary>
? ? ? ? /// 密碼
? ? ? ? /// </summary>
? ? ? ? public string UserPwd { get; set; }
? ? }
? ? /// <summary>
? ? /// 登錄返回
? ? /// </summary>
? ? public class MoLoginRp
? ? {
? ? ? ? /// <summary>
? ? ? ? /// 登錄返回的token
? ? ? ? /// </summary>
? ? ? ? public string Token { get; set; }
? ? }
新增一個(gè)登錄接口，代碼如：
/// <summary>
? ? ? ? /// 登錄接口
? ? ? ? /// </summary>
? ? ? ? /// <param name="rq">請(qǐng)求</param>
? ? ? ? /// <returns>響應(yīng)</returns>
? ? ? ? [HttpPost]
? ? ? ? public MoLoginRp Login(MoLoginRq rq)
? ? ? ? {
? ? ? ? ? ? MoLoginRp rp = new MoLoginRp();
? ? ? ? ? ? rp.Token = Guid.NewGuid().ToString();
? ? ? ? ? ? return rp;
? ? ? ? }
到這里基本的動(dòng)作都做完了，剩下的是上面我們說(shuō)的xml文件怎么來(lái)，又怎么和swagger關(guān)聯(lián)；
首先，看項(xiàng)目的App_Start文件夾里面應(yīng)該在安裝nuget包的時(shí)候會(huì)自動(dòng)增加一個(gè)?SwaggerConfig.cs?文件，里面就是swagger使用的一些設(shè)置，我們需要找到被注釋的：?//c.IncludeXmlComments(GetXmlCommentsPath());?代碼，取消注釋并創(chuàng)建一個(gè)?GetXmlCommentsPath()?方法（獲取xml注釋文件路徑） 如：
public static string GetXmlCommentsPath()
? ? ? ? {
? ? ? ? ? ? //D:/WebApplication/bin/WebApplication.xml
? ? ? ? ? ? return Path.Combine(
? ? ? ? ? ? ? ? AppDomain.CurrentDomain.BaseDirectory,
? ? ? ? ? ? ? ? "bin",
? ? ? ? ? ? ? ? string.Format("{0}.XML", typeof(SwaggerConfig).Assembly.GetName().Name));
? ? ? ? }
這個(gè)時(shí)候代碼基本完成了，還需要我們通過(guò)vs設(shè)置一下生成項(xiàng)目時(shí)自動(dòng)創(chuàng)建xml文件，如下：鼠標(biāo)右鍵起始項(xiàng)目-》屬性-》生成-》勾選xml文件
然后，鼠標(biāo)右鍵重新生成下項(xiàng)目，這個(gè)時(shí)候bin目錄就有了WebApplication.xml
這個(gè)xml文件內(nèi)容就是一些注釋的信息，具體各位自己點(diǎn)看看下xml內(nèi)容；到這里我們?cè)O(shè)置和代碼都弄完了，來(lái)看下swagger頁(yè)面效果，通過(guò)預(yù)覽?http://localhost:51847/swagger/ui/index?：
這個(gè)時(shí)候我們?cè)黾拥囊恍┪淖终f(shuō)明就完成了，這個(gè)時(shí)候細(xì)心的朋友能夠看出來(lái)我們的Action方法名稱(chēng)沒(méi)識(shí)別出來(lái)，這不符合我們命名規(guī)范，這里有兩種解決方案：
在action方法上增加?[ActionName("Login")]?標(biāo)記
修改WebApiConfig.cs文件的路由如："api/{controller}/{action}/{id}"
這里我采用后者，為了統(tǒng)一通過(guò)方法名來(lái)識(shí)別對(duì)應(yīng)接口：
swagger文檔支持在header中增加Token參數(shù)
對(duì)于api接口，我們通常在登錄后的其他操作都會(huì)讓調(diào)用方傳遞授權(quán)的token，而token一般做法是放在請(qǐng)求的header里面，swagger文檔為了測(cè)試方便可以把token放在header作為參數(shù)傳遞；首先創(chuàng)建測(cè)試接口GetNames：
/// <summary>
? ? ? ? /// 獲取用戶(hù)名稱(chēng)列表
? ? ? ? /// </summary>
? ? ? ? /// <returns></returns>
? ? ? ? [HttpPost]
? ? ? ? public List<string> GetNames()
? ? ? ? {
? ? ? ? ? ? List<string> list = new List<string> {"神牛001","神牛002", "神牛003" };
? ? ? ? ? ? return list;
? ? ? ? }
然后在App_Start/SwaggerConfig.cs文件中添加：
1 c.ApiKey("apiKey")
2 .Description("授權(quán)token")
3 .Name("token")
4 .In("header");
并啟動(dòng)：
1 EnableSwaggerUi(c =>2 ? ? { ? ?
3 c.EnableApiKeySupport("token", "header");
4 });
然后啟動(dòng)并在swagger界面輸入：
這個(gè)時(shí)候點(diǎn)擊try?it out請(qǐng)求接口，能夠在看到請(qǐng)求里面包含了token信息：
原文地址: https://www.cnblogs.com/wangrudong003/p/9010108.html
.NET社區(qū)新聞，深度好文，歡迎訪問(wèn)公眾號(hào)文章匯總 http://www.csharpkit.com
總結(jié)
以上是生活随笔為你收集整理的使用Swashbuckle构建RESTful风格文档的全部?jī)?nèi)容，希望文章能夠幫你解決所遇到的問(wèn)題。
- 上一篇： 利用Skywalking-netcore
- 下一篇： 你关心才值得分享 | K8S网络安全之访