Swagger接口文档
1.Swagger介绍
Swagger工具,用于为ASP.NET Core后端接口生成漂亮的API文档,API文档是前后端开发人员联系的纽带。
本文采用Swagger版本及ASP.NET Core版本如下。
项目 | 版本号 |
---|---|
Swashbuckle.AspNetCore | 5.0.0-rc4 |
ASP.NET Core | .Net Core 2.2 |
2.安装Swashbuckle.AspNetCore
2.1 控制台
Install-package Swashbuckle.AspNetCore -Version 5.0.0-rc4
2.2 Nuget包管理器
3.添加Swagger服务
//添加Swagger生成器服务
services.AddSwaggerGen(c=> {
//添加Swagger文档
c.SwaggerDoc("v1",new Microsoft.OpenApi.Models.OpenApiInfo { Title = "My API", Version = "v1" });
});
4.添加Swagger到中间件
app.UseSwagger();
app.UseSwaggerUI(c =>
{
c.SwaggerEndpoint("/swagger/v1/swagger.json", "My API V1");//Swagger文档路径
c.RoutePrefix = "";//设置为首页访问
});
4.接口添加注释文档
1.首先生成Xml文档
2.代码中配置
services.AddSwaggerGen(c=> {
//添加Swagger文档
c.SwaggerDoc("v1",new Microsoft.OpenApi.Models.OpenApiInfo { Title = "My API", Version = "v1" });
//
c.CustomOperationIds(apiDesc =>
{
return apiDesc.TryGetMethodInfo(out MethodInfo methodInfo) ? methodInfo.Name : null;
});
//接口添加注释
var filePath = Path.Combine(System.AppContext.BaseDirectory, "Swaggger5Test.xml");
c.IncludeXmlComments(filePath);
//Model添加注释
var modelPath = Path.Combine(System.AppContext.BaseDirectory, "Swagger5Test.Models.xml");
c.IncludeXmlComments(modelPath);
});
5.添加过滤器
添加Path过滤器,可以只显示以/api/Product的控制器的文档
//过滤器
app.UseSwagger(c => {
c.PreSerializeFilters.Add((swaggerDoc, httpReq) => {
OpenApiPaths paths = new OpenApiPaths();
foreach (var path in swaggerDoc.Paths)
{
if (path.Key.StartsWith("/api/Product"))//过滤Path
paths.Add(path.Key, path.Value);
}
swaggerDoc.Paths = paths;
swaggerDoc.Servers = new List<OpenApiServer> { new OpenApiServer { Url = $"{httpReq.Scheme}://{httpReq.Host.Value}" } };
});
});
6.设置首页访问
1.首先修改launchSettings.json文件
2.代码设置
app.UseSwaggerUI(c =>
{
c.SwaggerEndpoint("/swagger/v1/swagger.json", "My API V1");//Swagger文档路径
c.RoutePrefix = "";//设置为首页访问
});
7.注意
警告如何处理:给接口添加注释之后,如果有的接口没有添加注释,就会生成警告,解决方式是在取消显示警告中添加1591;如下图: