Asp.net Core Web API使用Swagger生成幫助頁，Swagger使用內置技術創建一個API接口的幫助頁面，頁面不僅使API接口一目了然，而且把接口注釋也顯示在幫助頁上，最大的特點是支持接口的在線測試。這些優點無疑使其比原先使用的Asp.net 內置的API幫助文檔更受歡迎。
1引用Swagger NuGet packages
- 使用程序包管理器控制臺窗口:
Install-Package Swashbuckle.AspNetCore - 使用NuGet管理界面安裝
右鍵項目>選擇管理NuGet選項>在管理解決方案包里面搜索Swashbuckle.AspNetCore>選擇Swashbuckle.AspNetCore并安裝。
Swashbuckle.AspNetCore安裝界面
2在項目中添加及設置ConfigureServices中間件
在Startup類的ConfigureServices方法添加如下代碼，使項目中添加ConfigureServices中間件
services.AddSwaggerGen(c =>
{
c.SwaggerDoc("v1", new Info { Title = "My API", Version = "v1" });
});
在Startup類的Configure，使項目能夠使用ConfigureServices中間件
app.UseSwagger();
app.UseSwaggerUI(c =>
{
c.SwaggerEndpoint("/swagger/v1/swagger.json", "My API V1");
c.RoutePrefix = "";//路徑配置，設置為空，表示直接訪問該文件
});
3運行調試
http://localhost:35030/swagger/ 不同的電腦可能會有不同的端口號
接口幫助文檔
調試接口
4啟用XML 注釋
image.png
另外上圖中，禁止顯示警告中，添加1591 代碼，可以過濾掉一些類名沒有寫注釋的報警信息
在Startup類的Configure方法上，修改使用ConfigureServices中間件的調用方法
services.AddSwaggerGen(c =>
{
c.SwaggerDoc("v1", new Info
{
Version = "v1",
Title = "ToDo API",
Description = "A simple example ASP.NET Core Web API ",
TermsOfService = "None",
Contact = new Contact { Name = "凌云木", Email = "825116693@qq.com", Url = "http://www.lxweimin.com/u/79758fa3d8b0" },
License = new License { Name = "Use under LICX", Url = "https://example.com/license" }
});
//為Swagger的JSON和UI設置XML注釋
var basePath = AppContext.BaseDirectory;
var xmlPath = Path.Combine(basePath, "TodoApi.xml");
c.IncludeXmlComments(xmlPath);
});
在前面的代碼中，AppicationBasePath獲取應用程序的基本了路徑。用來查找XML注釋文件.TodoApi.xml僅適用于此示例中，引文生成的XML注釋文件的名稱基于應用程序的名稱。
修改完運行調試
image.png
6 補充 （添加Model注釋）
以上步驟做完生成的文檔中，你會發現沒有Model的注釋，這不太完美，下面說下怎樣添加添加Model注釋
6.1新建一個.net core 類庫ApiModel，注意是 .net core的類庫
6.1 添加一個用戶類
/// <summary>
/// 登錄用戶類
/// </summary>
public class User
{
/// <summary>
/// 登陸用戶名
/// </summary>
public string Name { get; set; }
/// <summary>
/// 登錄密碼
/// </summary>
public string Pwd { get; set; }
}
6.2設置XML文件輸出
設置XML文件輸出
6.3修改Startup中的Swagger配置
services.AddSwaggerGen(c =>
{
c.SwaggerDoc("v1", new Info
{
Version = "v1",
Title = "凌云木 WebAPI",
Description = "A simple example ASP.NET Core Web API ",
TermsOfService = "None",
Contact = new Contact { Name = "凌云木", Email = "88888888@qq.com", Url = "http://www.lxweimin.com/u/79758fa3d8b0" },
License = new License { Name = "Use under LICX", Url = "https://example.com/license" }
});
//為Swagger的JSON和UI設置XML注釋
var basePath = AppContext.BaseDirectory;
var xmlPath = Path.Combine(basePath, "APIServer.xml");
c.IncludeXmlComments(xmlPath,true);
var xmlModelPath = Path.Combine(basePath, "ApiModel.xml");//這個就是Model層的xml文件名
c.IncludeXmlComments(xmlModelPath);
});
再次運行項目，Model的注釋出來了
Mode注釋
