使用Swashbuckle构建RESTful风格文档
本次和大家分享的是Swagger to WebApi的nuget包Swashbuckle；因為項目需要統一api文檔的風格，并要支持多種開發語言（C#，java，python），所以首先想到的是swagger來構建api文檔，本章講解的是對.net的webpi來生成文檔，后續會將java的springmvc+swagger來構建接口文檔。
準備工作
快速構建簡易api文檔
swagger文檔支持在header中增加Token參數
.?準備工作
首先創webapi項目，然后通過nuget管理器安裝Swashbuckle的包，我這里通過console命令安裝：
?Install-Package Swashbuckle -Version?5.6.0?
注意只需要安裝這個包就行了，其他的會自動引用，由于Swashbuckle包含了swagger的引用，所以不用再單獨操作引用了。
.?快速構建簡易api文檔
如上安裝完Swashbuckle后其實就能夠直接運行看效果了，我這里的訪問路徑是：?http://localhost:51847/swagger/ui/index?，注意：/swagger/ui/index?是默認固定的路徑，這是nuget包封裝的路徑，訪問后能看到如下界面效果：
一個簡易的文檔就弄好了，swagger的顏色看起來搭配不錯；由于大多數接口都是post請求方式，因此咋們以/api/values的post接口為例如：
對于接口文檔而言，上面文檔存在如下一些疏漏：
未說明方法的功能
參數屬性的描述沒有
返回屬性的描述沒有
為了方便其他人員對接接口，所以對接口文檔我們需要增加一些描述，要增加描述這里就要知曉：Swashbuckle是通過xml文件來讀取配置信息的，該xml文件里面包含了我們在代碼中對方法，對類，對參數，對返回值做的文字描述；首先定義一個請求和響應的實體?如：
/// <summary>
? ? /// 登錄請求
? ? /// </summary>
? ? public class MoLoginRq
? ? {
? ? ? ? /// <summary>
? ? ? ? /// 賬號
? ? ? ? /// </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; }
? ? }
新增一個登錄接口，代碼如：
/// <summary>
? ? ? ? /// 登錄接口
? ? ? ? /// </summary>
? ? ? ? /// <param name="rq">請求</param>
? ? ? ? /// <returns>響應</returns>
? ? ? ? [HttpPost]
? ? ? ? public MoLoginRp Login(MoLoginRq rq)
? ? ? ? {
? ? ? ? ? ? MoLoginRp rp = new MoLoginRp();
? ? ? ? ? ? rp.Token = Guid.NewGuid().ToString();
? ? ? ? ? ? return rp;
? ? ? ? }
到這里基本的動作都做完了，剩下的是上面我們說的xml文件怎么來，又怎么和swagger關聯；
首先，看項目的App_Start文件夾里面應該在安裝nuget包的時候會自動增加一個?SwaggerConfig.cs?文件，里面就是swagger使用的一些設置，我們需要找到被注釋的：?//c.IncludeXmlComments(GetXmlCommentsPath());?代碼，取消注釋并創建一個?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));
? ? ? ? }
這個時候代碼基本完成了，還需要我們通過vs設置一下生成項目時自動創建xml文件，如下：鼠標右鍵起始項目-》屬性-》生成-》勾選xml文件
然后，鼠標右鍵重新生成下項目，這個時候bin目錄就有了WebApplication.xml
這個xml文件內容就是一些注釋的信息，具體各位自己點看看下xml內容；到這里我們設置和代碼都弄完了，來看下swagger頁面效果，通過預覽?http://localhost:51847/swagger/ui/index?：
這個時候我們增加的一些文字說明就完成了，這個時候細心的朋友能夠看出來我們的Action方法名稱沒識別出來，這不符合我們命名規范，這里有兩種解決方案：
在action方法上增加?[ActionName("Login")]?標記
修改WebApiConfig.cs文件的路由如："api/{controller}/{action}/{id}"
這里我采用后者，為了統一通過方法名來識別對應接口：
swagger文檔支持在header中增加Token參數
對于api接口，我們通常在登錄后的其他操作都會讓調用方傳遞授權的token，而token一般做法是放在請求的header里面，swagger文檔為了測試方便可以把token放在header作為參數傳遞；首先創建測試接口GetNames：
/// <summary>
? ? ? ? /// 獲取用戶名稱列表
? ? ? ? /// </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("授權token")
3 .Name("token")
4 .In("header");
并啟動：
1 EnableSwaggerUi(c =>2 ? ? { ? ?
3 c.EnableApiKeySupport("token", "header");
4 });
然后啟動并在swagger界面輸入：
這個時候點擊try?it out請求接口，能夠在看到請求里面包含了token信息：
原文地址: https://www.cnblogs.com/wangrudong003/p/9010108.html
.NET社區新聞，深度好文，歡迎訪問公眾號文章匯總 http://www.csharpkit.com
總結
以上是生活随笔為你收集整理的使用Swashbuckle构建RESTful风格文档的全部內容，希望文章能夠幫你解決所遇到的問題。
- 上一篇： 利用Skywalking-netcore
- 下一篇： 发布 Rafy .NET Standar