Asp.Net Core SwaggerUI 接入
简单了解
swagger
的目的简单来说就是,不用为每个接口手动写接口文档,因为它是根据接口自动生成的,接口更改时文档也同步更新,减少了手动更新的麻烦和遗漏。同时也提供了接口的调试等功能,你不用打开postman
等接口测试软件来测试接口;如果有写备注的话,接口、入参和输出都有详细的备注说明,调用接口的人也能更加直观的读懂接口。沟通效率和工作效率也会大大提升。
Swagger接入的步骤:
- 注册
Swagger
生成器:services.AddSwaggerGen()
. - 插入中间件,将生成的
Swagger
公开为JSON
节点:app.UseSwagger()
- 插入
Swagger-UI
中间件,将指定的swagger json
端点为其提供支持:app.UseSwaggerUI()
一、添加Nuget包
Package Manager : Install-Package Swashbuckle.AspNetCore
或
CLI : dotnet add package Swashbuckle.AspNetCore
二、注册swagger文档服务
-
注意
-
如果mvc使用的是
services.AddMvcCore()
,则需要手动添加ApiExplorer
,因为SwashBuckle
强烈依赖于ApiExplorer
,ApiExplorer
用来发现控制器中的接口方法。需要手动添加。如:
services.AddMvcCore().AddApiExplorer();
-
如果使用的是
services.AddMvc()
,则不需要再进行注册。因为AddMvc()
中已经添加了ApiExplorer
。如:public static IMvcBuilder AddMvc(this IServiceCollection services) { if (services == null) throw new ArgumentNullException(nameof (services)); IMvcCoreBuilder builder = services.AddMvcCore(); builder.AddApiExplorer();//在这里 builder.AddAuthorization(); MvcServiceCollectionExtensions.AddDefaultFrameworkParts(builder.PartManager); builder.AddFormatterMappings(); builder.AddViews(); builder.AddRazorViewEngine(); builder.AddRazorPages(); builder.AddCacheTagHelper(); builder.AddDataAnnotations(); builder.AddJsonFormatters(); builder.AddCors(); return (IMvcBuilder) new MvcBuilder(builder.Services, builder.PartManager); }
-
什么时候用
AddMvc()
,什么时候用AddMvcCore()
呢?
通过AddMvc()
的方法中我们应该可以发现,里面有添加View
、Razor
和TagHelper
服务,这些在WebApi项目中是用不到的。所以:
1).如果你的项目是mvc web程序,则使用AddMvc()
.
2).如果的项目是webapi,则使用AddMvcCore()
,然后酌情添加需要的其它服务;当然使用AddMvc()
也没有问题。
-
添加Swagger服务
services.AddSwaggerGen(options =>
{
options.SwaggerDoc(AppDefaults.ApiDocumentName, new Info
{
Title = AppDefaults.ApiDocumentTitle,
Description = AppDefaults.ApiDocumentDescription,
Version = typeof(Startup).Assembly.GetName().Version.ToString()
});
//加载注释文件
Directory.GetFiles(Environment.ContentRootPath, "*.xml", SearchOption.AllDirectories)
.ToList()
.ForEach(f => options.IncludeXmlComments(f));
});
三、添加管道
//生成swagger-json文件,并重定义swagger-json文件路由模板,这里我修改了 swagger-json 的路由模板。
//如果不自定义的话,默认是 swagger/{documentName}/swagger.json
app.UseSwagger(options => options.RouteTemplate = "{documentName}/swagger.json");
app.UseSwaggerUI(options =>
{
//指定生成swagger-json文件路径,为SwaggerUI提供数据。
//如果上边路由模板没有自定义,则完成路径是 /swagger/{AppDefaults.ApiDocumentName}/swagger.json
options.SwaggerEndpoint($"/{AppDefaults.ApiDocumentName}/swagger.json", AppDefaults.ApiDocumentName);
//自定义SwaggerUI页面路由前缀
//地址栏输入 http://loacalhost:5000/lxp 就可以打开SwaggerUI页面
options.RoutePrefix = "lxp";
});
四、定义接口
- 如果想要控制器在
Swagger
中显示,所有控制器必须使用属性路由 - 接口方法要使用 Http 属性和 From 特性标注
例如:
[Route("[controller]")]
[ApiController]
public class ValuesController : ControllerBase
{
[HttpGet("name")]
public async Task<ActionResult<string>> GetNameAsync([FromQuery] string name)
{
if (!string.IsNullOrEmpty(name))
{
ModelState.TryAddModelError(nameof(name), $"{nameof(name)} can not be empty");
}
if (!ModelState.IsValid)
{
return BadRequest(ModelState);
}
return await Task.FromResult(name);
}
}
补充:
AppDefaults
是我定义一个常量的类