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 = "https://www.jianshu.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 = "https://www.jianshu.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注释
