本次和大家分享的是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风格文档的全部內容，希望文章能夠幫你解決所遇到的問題。

如果覺得生活随笔網站內容還不錯，歡迎將生活随笔推薦給好友。