首先微软官方给了简单的例子,参考这个例子就可以生成简单的可视化文档。
微软官网文档地址:点击打开链接
首先新建一个WebAPI项目,Edu.Swagger
然后打开“程序包管理控制台”使用NuGet安装 Swashbuckle.AspNetCore
Install-Package Swashbuckle.AspNetCore
配置Startup.cs文件
将 Swagger 生成器添加到 Startup.ConfigureServices 方法中的服务集合中:
下面我用v1,v2分别表示两个版本的接口
services.AddSwaggerGen(option =>
{
option.SwaggerDoc("v1", new Info
{
Version = "v1",
Title = "第一版 API",
Description = "第一版 ASP.NET Core Web API",
TermsOfService = "None",
Contact = new Contact
{
Name = "张海涛",
Email = "993887459@qq.com",
Url = "https://blog.csdn.net/haitaoDoit"
},
License = new License
{
Name = "Use under LICX",
Url = "https://example.com/license"
}
});
option.SwaggerDoc("v2", new Info
{
Version = "v2",
Title = "第二版 API",
Description = "第二版 ASP.NET Core Web API",
TermsOfService = "None",
Contact = new Contact
{
Name = "张海涛",
Email = "993887459@qq.com",
Url = "https://blog.csdn.net/haitaoDoit"
},
License = new License
{
Name = "Use under LICX",
Url = "https://example.com/license"
}
});
在 Startup.Configure
方法中,启用中间件为生成的 JSON 文档和 Swagger UI 提供服务:
app.UseSwagger();
app.UseSwaggerUI(c =>
{
c.SwaggerEndpoint("/swagger/v1/swagger.json", "My API V1");
c.SwaggerEndpoint("/swagger/v2/swagger.json", "My API V2");
});
现在启动浏览器
最基本的UI界面已经出来了,但是现在是没有获取到方法描述的。
右键项目属性,启用XML文档文件,并且添加1591禁止显示警告
在Startup.ConfigureServices 中services.AddSwaggerGen(option =>添加
为 Swagger JSON and UI设置xml文档注释路径
option.IncludeXmlComments(Path.Combine(AppDomain.CurrentDomain.BaseDirectory, "Edu.Model.xml"));//这里增加model注释,返回值会增加注释:需要Edu.Model项目属性,生成中输出xml文件
option.IncludeXmlComments(Path.Combine(AppDomain.CurrentDomain.BaseDirectory, "Edu.Swagger.xml"));
再次运行项目,就可以看到代码中的说明了
前面我们提到我们设计了两个版本,v1,v2,那么怎么实现呢,下面在代码中添加
[ApiExplorerSettings(GroupName = "v1")]
[ApiExplorerSettings(GroupName = "v2")]
再次运行项目,默认打开V1版本
点击右上角下拉框选择V2那么就会显示V2的接口
本文Demo下载地址:点击打开链接
GitHub地址:https://github.com/zhanght919/Edu.Swagger
总结
本文从手工书写api文档的痛处说起,进而引出Swagger这款自动生成api说明文档的工具!然后通过通俗易懂的文字结合图片为大家演示了如何在一个ASP.NET Core WebApi中使用SwaggerUI生成api说明文档。最后又为大家介绍了一些ASP.NET Core 中Swagger的一些高级用法!希望对大家在ASP.NET Core中使用Swagger有所帮助!