);
然后运行项目,输入http://localhost:5000/swagger,得到接口文档页面:
点击Try it out可以直接调用接口。
这里,发现接口没有注解说明,这不太友好,而Swashbuckle的接口可以从代码注释中获取,也可以使用代码说明,我们做开发的当然想直接从注释获取啦。
但是另一方面,因为注释在代码编译时会被过滤掉,因此我们需要在项目中生成注释文件,然后让程序加载注释文件,操作如下:
右键项目=》切换到生成(Build),在最下面输出输出中勾选【XML文档文件】,同时,在错误警告的取消显示警告中添加1591代码:
注:建议这里添加1591,因为如果不添加,而且勾选【XML文档文件】,那么如果代码中没有注释,项目将会抛出茫茫多的警告,而1591则表示取消这种无注释的警告
生成当前项目时会将项目中所有的注释打包到这个文件中。
然后修改ConfigureServices:
public void ConfigureServices(IServiceCollection services)
{
...
services.AddSwaggerGen(options =>
options.SwaggerDoc("v1", new OpenApiInfo()
Version = "v0.0.1",
Title = "swagger测试项目",
Description = $"接口文档说明",
Contact = new OpenApiContact()
Name = "zhangsan",
Email = "xxx@qq.com",
Url = null
options.IncludeXmlComments("SwashbuckleDemo.xml", true);
上面使用IncludeXmlComments方法加载注释,第二个参数true表示注释文件包含了控制器的注释,如果不包含控制器注释(如引用的其他类库),可以将它置为false
注意上面的xml文件要与它对应的dll文件放到同目录,如果不在同一目录,需要自行指定目录,如果找不到文件,可能会抛出异常!。
另外,如果项目引用的其他项目,可以将其他项目也生成xml注释文件,然后使用IncludeXmlComments方法加载,从而避免部分接口信息无注解情况
运行后可以得到接口的注释:
接着,既然是提供接口,没有认证怎么行,比如,Home控制器下还有一个Post接口,但是接口需要认证,比如JwtBearer认证:
/// <summary>
/// 测试接口
/// </summary>
[ApiController]
[Route("[controller]")]
public class HomeController : ControllerBase
/// <summary>
/// 使用认证获取数据
/// </summary>
/// <returns>返回数据</returns>
[HttpPost, Authorize]
public string Post()
return "这是认证后的数据";
为了接口能使用认证,修改Startup的ConfigureServices:
public void ConfigureServices(IServiceCollection services)
{
...
services.AddSwaggerGen(options =>
options.SwaggerDoc("v1", new OpenApiInfo()
Version = "v0.0.1",
Title = "swagger测试项目",
Description = $"接口文档说明",
Contact = new OpenApiContact()
Name = "zhangsan",
Email = "xxx@qq.com",
Url = null
options.IncludeXmlComments("SwashbuckleDemo.xml", true);//第二个参数true表示注释文件包含了控制器的注释
//定义JwtBearer认证方式一
options.AddSecurityDefinition("JwtBearer", new OpenApiSecurityScheme()
Description = "这是方式一(直接在输入框中输入认证信息,不需要在开头添加Bearer)",
Name = "Authorization",//jwt默认的参数名称
In = ParameterLocation.Header,//jwt默认存放Authorization信息的位置(请求头中)
Type = SecuritySchemeType.Http,
Scheme = "bearer"
//定义JwtBearer认证方式二
//options.AddSecurityDefinition("JwtBearer", new OpenApiSecurityScheme()
// Description = "这是方式二(JWT授权(数据将在请求头中进行传输) 直接在下框中输入Bearer {token}(注意两者之间是一个空格))",
// Name = "Authorization",//jwt默认的参数名称
// In = ParameterLocation.Header,//jwt默认存放Authorization信息的位置(请求头中)
// Type = SecuritySchemeType.ApiKey
//});
//声明一个Scheme,注意下面的Id要和上面AddSecurityDefinition中的参数name一致
var scheme = new OpenApiSecurityScheme()
Reference = new OpenApiReference() { Type = ReferenceType.SecurityScheme, Id = "JwtBearer" }
//注册全局认证(所有的接口都可以使用认证)
options.AddSecurityRequirement(new OpenApiSecurityRequirement()
[scheme] = new string[0]
});
...
程序运行后效果如下:
上面说了,添加JwtBearer认证有两种方式,两种方式的区别如下:
到这里应该就已经满足大部分需求的用法了,这也是网上很容易就能搜索到的,接下来介绍的是一些常用到的方法。
二、服务注入(AddSwaggerGen)
前面介绍到,Swashbuckle的服务注入是在ConfigureServices中使用拓展方法AddSwaggerGen实现的
services.AddSwaggerGen(options =>
//使用options注入服务
确切的说swagger的服务注入是使用SwaggerGenOptions来实现的,下面主要介绍SwaggerGenOptions的一些常用的方法:
SwaggerDoc
SwaggerDoc主要用来声明一个文档,上面的例子中声明了一个名称为v1的接口文档,当然,我们可以声明多个接口文档,比如按开发版本进行声明:
options.SwaggerDoc("v1", new OpenApiInfo()
Version = "v0.0.1",
Title = "项目v0.0.1",
Description = $"接口文档说明v0.0.1",
Contact = new OpenApiContact()
Name = "zhangsan",
Email = "xxx@qq.com",
Url = null
options.SwaggerDoc("v2", new OpenApiInfo()
Version = "v0.0.2",
Title = "项目v0.0.2",
Description = $"接口文档说明v0.0.2",
Contact = new OpenApiContact()
Name = "lisi",
Email = "xxxx@qq.com",
Url = null
});
...
开发过程中,可以将接口文档名称设置成枚举或者常量值,以方便文档名的使用。
至于上面OpenApiInfo声明的各参数,其实就是要在SwaggerUI页面上展示出来的,读者可自行测试一下,这里不过多说明,只是顺带提一下Description属性,这个是一个介绍文档接口的简介,但是这个属性是支持html展示的,也就是说可以生成一些html代码放到Description属性中。
声明多个文档,可以将接口进行归类,不然一个项目几百个接口,查看起来也不方便,而将要接口归属某个文档,我们可以使ApiExplorerSettingsAttribute指定GroupName来指定,如:
/// <summary>
/// 未使用ApiExplorerSettings特性,表名属于每一个swagger文档
/// </summary>
/// <returns>结果</returns>
[HttpGet("All")]
public string All()
return "All";
/// <summary>
/// 使用ApiExplorerSettings特性表名该接口属于swagger文档v1
/// </summary>
/// <returns>Get结果</returns>
[HttpGet]
[ApiExplorerSettings(GroupName = "v1")]
public string Get()
return "Get";
/// <summary>
/// 使用ApiExplorerSettings特性表名该接口属于swagger文档v2
/// </summary>
/// <returns>Post结果</returns>
[HttpPost]
[ApiExplorerSettings(GroupName = "v2")]
public string Post()
return "Post";
因为我们现在有两个接口文档了,想要在swaggerUI中看得到,还需要在中间件中添加相关文件的swagger.json文件的入口:
public void Configure(IApplicationBuilder app, IWebHostEnvironment env)
app.UseSwagger();
app.UseSwaggerUI(options =>
options.SwaggerEndpoint("/swagger/v1/swagger.json", "v1");
options.SwaggerEndpoint("/swagger/v2/swagger.json", "v2");
运行项目后:
上面使用ApiExplorerSettingsAttribute的GroupName属性指定归属的swagger文档(GroupName需要设置成上面SwaggerDoc声明的文档的名称),如果不使用ApiExplorerSettingsAttribute,那么接口将属于所有的swagger文档,上面的例子可以看到/Home/All接口既属于v1也属于v2。
另外ApiExplorerSettingsAttribute还有个IgnoreApi属性,如果设置成true,将不会在swagger页面展示该接口。
但是接口一个个的去添加ApiExplorerSettingsAttribute,是不是有点繁琐了?没事,我们可以采用Convertion实现,主要是IActionModelConvention和IControllerModelConvention两个:
IActionModelConvention方式:
public class GroupNameActionModelConvention : IActionModelConvention
public void Apply(ActionModel action)
if (action.Controller.ControllerName == "Home")
if (action.ActionName == "Get")
action.ApiExplorer.GroupName = "v1";
action.ApiExplorer.IsVisible = true;
else if (action.ActionName == "Post")
action.ApiExplorer.GroupName = "v2";
action.ApiExplorer.IsVisible = true;
然后在ConfigureService中使用:
services.AddControllers(options =>
options.Conventions.Add(new GroupNameActionModelConvention());
或者使用IControllerModelConvention方式:
public class GroupNameControllerModelConvention : IControllerModelConvention
public void Apply(ControllerModel controller)
if (controller.ControllerName == "Home")
foreach (var action in controller.Actions)
if (action.ActionName == "Get")
action.ApiExplorer.GroupName = "v1";
action.ApiExplorer.IsVisible = true;
else if (action.ActionName == "Post")
action.ApiExplorer.GroupName = "v2";
action.ApiExplorer.IsVisible = true;
然后在ConfigureService中使用:
services.AddControllers(options =>
options.Conventions.Add(new GroupNameControllerModelConvention());
这两种方式实现的效果和使用ApiExplorerSettingsAttribute是一样的,细心的朋友可能会注意,action.ApiExplorer.GroupName与ApiExplorerSettingsAttribute.GroupName是对应的,action.ApiExplorer.IsVisible则与ApiExplorerSettingsAttribute.IgnoreApi是对应的
IncludeXmlComments
IncludeXmlComments是用于加载注释文件,Swashbuckle会从注释文件中去获取接口的注解,接口参数说明以及接口返回的参数说明等信息,这个在上面的一般用法中已经介绍了,这里不再重复说明
IgnoreObsoleteActions
IgnoreObsoleteActions表示过滤掉ObsoleteAttribute属性声明的接口,也就是说不会在SwaggerUI中显示接口了,ObsoleteAttribute修饰的接口表示接口已过期,尽可能不要再使用。
方法调用等价于:
options.SwaggerGeneratorOptions.IgnoreObsoleteActions = true;
IgnoreObsoleteProperties
IgnoreObsoleteProperties的作用类似于IgnoreObsoleteActions,只不过IgnoreObsoleteActions是作用于接口,而IgnoreObsoleteProperties作用于接口的请求实体和响应实体参数中的属性。
方法调用等价于:
options.SchemaGeneratorOptions.IgnoreObsoleteProperties = true;
OrderActionsBy
OrderActionsBy用于同一组接口(可以理解为同一控制器下的接口)的排序,默认情况下,一般都是按接口所在类的位置进行排序(源码中是按控制器名称排序,但是同一个控制器中的接口是一样的)。
比如上面的例子中,我们可以修改成按接口路由长度排序:
options.OrderActionsBy(apiDescription => apiDescription.RelativePath.Length.ToString());
运行后Get接口和Post接口就在All接口前面了:
需要注意的是,OrderActionsBy提供的排序只有升序,其实也就是调用IEnumerable<ApiDescription>的OrderBy方法,虽然不理解为什么只有升序,但降序也是可以采用这个升序实现的,将就着用吧。
CustomSchemaIds
CustomSchemaIds方法用于自定义SchemaId,Swashbuckle中的每个Schema都有唯一的Id,框架会使用这个Id匹配引用类型,因此这个Id不能重复。
默认情况下,这个Id是根据类名得到的(不包含命名空间),因此,当我们有两个相同名称的类时,Swashbuckle就会报错:
System.InvalidOperationException: Can't use schemaId "$XXXXX" for type "$XXXX.XXXX". The same schemaId is already used for type "$XXXX.XXXX.XXXX"
就是类似上面的异常,一般时候我们都得去改类名,有点不爽,这时就可以使用这个方法自己自定义实现SchemaId的获取,比如,我们自定义实现使用类名的全限定名(包含命名空间)来生成SchemaId,上面的异常就没有了:
options.CustomSchemaIds(CustomSchemaIdSelector);
string CustomSchemaIdSelector(Type modelType)
if (!modelType.IsConstructedGenericType) return modelType.FullName.Replace("[]", "Array");
var prefix = modelType.GetGenericArguments()
.Select(genericArg => CustomSchemaIdSelector(genericArg))
.Aggregate((previous, current) => previous + current);
return prefix + modelType.FullName.Split('`').First();
TagActionsBy
Tag是标签组,也就是将接口做分类的一个概念。
TagActionsBy用于获取一个接口所在的标签分组,默认的接口标签分组是控制器名,也就是接口被分在它所属的控制器下面,我们可以改成按请求方法进行分组
options.TagActionsBy(apiDescription => new string[] { apiDescription.HttpMethod});
注意到,上面还有一个Home空标签,如果不想要这个空标签,可以将它的注释去掉,(不明白为什么Swashbuckle为什么空标签也要显示出来,难道是因为作者想着只要有东西能展示,就应该显示出来?)
MapType
MapType用于自定义类型结构(Schema)的生成,Schema指的是接口参数和返回值等的结构信息。
比如,我有一个获取用户信息的接口:
/// <summary>
/// 获取用户
/// </summary>
/// <returns>用户信息</returns>
[HttpGet("GetUser")]
public User GetUser(int id)
//这里根据Id获取用户信息
return new User()
Name = "张三"
其中User是自己定义的一个实体
/// <summary>
/// 用户信息
/// </summary>
public class User
/// <summary>
/// 用户名称
/// </summary>
public string Name { get; set; }
/// <summary>
/// 用户密码
/// </summary>
public string Password { get; set; }
/// <summary>
/// 手机号码
/// </summary>
public string Phone { get; set; }
/// <summary>
/// 工作
/// </summary>
public string Job { get; set; }
默认情况下,swagger生成的结构是json格式:
通过MapType方法,可以修改User生成的架构,比如修改成字符串类型:
options.MapType<User>(() =>
return new OpenApiSchema() {
Type= "string"
运行后显示:
AddServer
Server指的是接口访问的域名和前缀(虚拟路径),以方便访问不同地址的接口(注意设置跨域).
AddServer用于全局的添加接口域名和前缀(虚拟路径)部分信息,默认情况下,如果我们在SwaggerUi页面使用Try it out去调用接口时,默认使用的是当前swaggerUI页面所在的地址域名信息:
而AddServer方法运行我们添加其他的地址域名,比如:
options.AddServer(new OpenApiServer() { Url = "http://localhost:5000", Description = "地址1" });
options.AddServer(new OpenApiServer() { Url = "http://127.0.0.1:5001", Description = "地址2" });
//192.168.28.213是我本地IP
options.AddServer(new OpenApiServer() { Url = "http://192.168.28.213:5002", Description = "地址3" });
我分别在上面3个端口开启程序,运行后:
注意:如果读者本地访问不到,看看自己程序是否有监听这三个地址,而且记得要设置跨域,否则会导致请求失败:
public void ConfigureServices(IServiceCollection services)
...
services.AddCors();
}
public void Configure(IApplicationBuilder app, IWebHostEnvironment env)
{
...
app.UseCors(builder =>
{
builder.AllowAnyOrigin().AllowAnyMethod().AllowAnyHeader();
});
...
}
在开发过程中,我们的程序可能会发布到不同的环境,比如本地开发环境,测试环境,预生产环境等等,因此,我们可以使用AddServer方法将不同环境的地址配置上去就能直接实现调用了。
在项目部署时,可能会涉及到虚拟目录之类的东西,比如,使用IIS部署时,可能会给项目加一层虚拟路径:
或者使用nginx做一层反向代理:
这个时候虽然可以使用http://ip:port/Swashbuckle/swagger/index.html访问到swaggerUI,但是此时可能会报错 Not Found /swagger/v1/swagger.json:
这是因为加了虚拟路径,而swagger并不知道,所以再通过/swagger/v1/swagger.json去获取接口架构信息当然会报404了,我们可以改下Swagger中间件:
app.UseSwagger();
app.UseSwaggerUI(options =>
options.SwaggerEndpoint("/Swashbuckle/swagger/v1/swagger.json", "v1");
options.SwaggerEndpoint("/Swashbuckle/swagger/v2/swagger.json", "v2");
再使用虚拟路径就可以访问到SwaggerUI页面了,但是问题还是有的,因为所有接口都没有加虚拟路径,上面说道,swagger调用接口默认是使用SwaggerUI页面的地址+接口路径去访问的,这就会少了虚拟路径,访问自然就变成了404:
这个时候就可以调用AddServer方法去添加虚拟路径了:
//注意下面的端口,已经变了
options.AddServer(new OpenApiServer() { Url = "http://localhost:90/Swashbuckle", Description = "地址1" });
options.AddServer(new OpenApiServer() { Url = "http://127.0.0.1:90/Swashbuckle", Description = "地址2" });
//192.168.28.213是我本地IP
options.AddServer(new OpenApiServer() { Url = "http://192.168.28.213:90/Swashbuckle", Description = "地址3" });
部署运行后就可以访问了:
一般的,开发过程中,我们可以把这个虚拟路径做成配置,在然后从配置读取即可。
注:我记得Swashbuckle在swagger2.0的版本中SwaggerDocument中有个BasePath,可以很轻松的设置虚拟路径,但是在swagger3+之后把这个属性删除了,不知道什么原因
AddSecurityDefinition
AddSecurityDefinition用于声明一个安全认证,注意,只是声明,并未指定接口必须要使用认证,比如声明JwtBearer认证方式:
//定义JwtBearer认证方式一
options.AddSecurityDefinition("JwtBearer", new OpenApiSecurityScheme()
Description = "这是方式一(直接在输入框中输入认证信息,不需要在开头添加Bearer)",
Name = "Authorization",//jwt默认的参数名称
In = ParameterLocation.Header,//jwt默认存放Authorization信息的位置(请求头中)
Type = SecuritySchemeType.Http,
Scheme = "bearer"
AddSecurityDefinition方法需要提供一个认证名以及一个OpenApiSecurityScheme对象,而这个OpenApiSecurityScheme对象就是描述的认证信息,常用的有:
Type:表示认证方式,有ApiKey,Http,OAuth2,OpenIdConnect四种,其中ApiKey是用的最多的。
Description:认证的描述
Name:携带认证信息的参数名,比如Jwt默认是Authorization
In:表示认证信息发在Http请求的哪个位置
Scheme:认证主题,只对Type=Http生效,只能是basic和bearer
BearerFormat::Bearer认证的数据格式,默认为Bearer Token(中间有一个空格)
Flows:OAuth认证相关设置,比如认证方式等等
OpenIdConnectUrl:使用OAuth认证和OpenIdConnect认证的配置发现地址
Extensions:认证的其他拓展,如OpenIdConnect的Scope等等
Reference:关联认证
这些属性中,最重要的当属Type,它指明了认证的方式,用通俗的话讲:
ApiKey表示就是提供一个框,你填值之后调用接口,会将填的值与Name属性指定的值组成一个键值对,放在In参数指定的位置通过http传送到后台。
Http也是提供了一个框,填值之后调用接口,会将填的值按照Scheme指定的方式进行处理,再和Name属性组成一个键值对,放在In参数指定的位置通过http传送到后台。这也就解释了为什么Bearer认证可以有两种方式。
OAuth2,OpenIdConnect需要提供账号等信息,然后去远程服务进行授权,一般使用Swagger都不推荐使用这种方式,因为比较复杂,而且授权后的信息也可以通过ApiKey方式传送到后台。
再举个例子,比如我们使用Cookie认证:
options.AddSecurityDefinition("Cookies", new OpenApiSecurityScheme()
Description = "这是Cookie认证方式",
Name = "Cookies",//这个是Cookie名
In = ParameterLocation.Cookie,//信息保存在Cookie中
Type = SecuritySchemeType.ApiKey
注:如果将信息放在Cookie,那么在SwaggerUI中调用接口时,认证信息可能不会被携带到后台,因为浏览器不允许你自己操作Cookie,因此在发送请求时会过滤掉你自己设置的Cookie,但是SwaggerUI页面调用生成的Curl命令语句是可以成功访问的
好了,言归正传,当添加了上面JwtBearer认证方式后,这时SwaggerUI多了一个认证的地方:
但是这时调用接口并不需要认证信息,因为还没有指定哪些接口需要认证信息
AddSecurityRequirement
AddSecurityDefinition仅仅是声明已一个认证,不一定要对接口用,而AddSecurityRequirement是将声明的认证作用于所有接口(AddSecurityRequirement好像可以声明和引用一起实现),比如将上面的JwtBearer认证作用于所有接口:
//声明一个Scheme,注意下面的Id要和上面AddSecurityDefinition中的参数name一致
var scheme = new OpenApiSecurityScheme()
Reference = new OpenApiReference() { Type = ReferenceType.SecurityScheme, Id = "JwtBearer" }
//注册全局认证(所有的接口都可以使用认证)
options.AddSecurityRequirement(new OpenApiSecurityRequirement()
[scheme] = new string[0]
运行后,发现所有接口后面多了一个锁,表明此接口需要认证信息:
AddSecurityRequirement调用需要一个OpenApiSecurityRequirement对象,他其实是一个字典型,也就是说可以给接口添加多种认证方式,而它的键是OpenApiSecurityScheme对象,比如上面的例子中将新定义的OpenApiSecurityScheme关联到已经声明的认证上,而值是一个字符串数组,一般指的是OpenIdConnect的Scope。
需要注意的是,AddSecurityRequirement声明的作用是对全部的接口生效,也就是说所有接口后面都会加锁,但这并不影响我们接口的调用,毕竟调用逻辑还是由后台代码决定的,但是这里加锁就容易让人误导以为都需要认证。
DocumentFilter
document顾名思义,当然指的就是swagger文档了。
DocumentFilter是文档过滤器,它是在获取swagger文档接口,返回结果前调用,也就是请求swagger.json时调用,它允许我们对即将返回的swagger文档信息做调整,比如上面的例子中添加的全局认证方式和AddSecurityRequirement添加的效果是一样的:
public class MyDocumentFilter : IDocumentFilter
public void Apply(OpenApiDocument swaggerDoc, DocumentFilterContext context)
//声明一个Scheme,注意下面的Id要和上面AddSecurityDefinition中的参数name一致
var scheme = new OpenApiSecurityScheme()
Reference = new OpenApiReference() { Type = ReferenceType.SecurityScheme, Id = "JwtBearer" }
//注册全局认证(所有的接口都可以使用认证)
swaggerDoc.SecurityRequirements.Add(new OpenApiSecurityRequirement()
[scheme] = new string[0]
然后使用DocumentFilter方法添加过滤器:
options.DocumentFilter<MyDocumentFilter>();
DocumentFilter方法需要提供一个实现了IDocumentFilter接口的Apply方法的类型和它实例化时所需要的的参数,而IDocumentFilter的Apply方法提供了OpenApiDocument和DocumentFilterContext两个参数,DocumentFilterContext参数则包含了当前文件接口方法的信息,比如调用的接口的Action方法和Action的描述(如路由等)。而OpenApiDocument即包含当前请求的接口文档信息,它包含的属性全部都是全局性的, 这样我们可以像上面添加认证一样去添加全局配置,比如,如果不使用AddServer方法,我们可以使用DocumentFilter去添加:
public class MyDocumentFilter : IDocumentFilter
public void Apply(OpenApiDocument swaggerDoc, DocumentFilterContext context)
swaggerDoc.Servers.Add(new OpenApiServer() { Url = "http://localhost:90", Description = "地址1" });
swaggerDoc.Servers.Add(new OpenApiServer() { Url = "http://127.0.0.1:90", Description = "地址2" });
//192.168.28.213是我本地IP
swaggerDoc.Servers.Add(new OpenApiServer() { Url = "http://192.168.28.213:90", Description = "地址3" });
记得使用DocumentFilter添加过滤器。
再比如,上面我们对接口进行了swagger文档分类使用的是ApiExplorerSettingsAttribute,如果不想对每个接口使用ApiExplorerSettingsAttribute,我们可以使用DocumentFilter来实现,先创建一个类实现IDocumentFilter接口:
public class GroupNameDocumentFilter : IDocumentFilter
string documentName;
string[] actions;
public GroupNameDocumentFilter(string documentName, params string[] actions)
this.documentName = documentName;
this.actions = actions;
public void Apply(OpenApiDocument swaggerDoc, DocumentFilterContext context)
foreach (var apiDescription in context.ApiDescriptions)
if (actions.Contains(apiDescription.ActionDescriptor.RouteValues["action"]))
apiDescription.GroupName = documentName;
然后使用DocumentFilter添加过滤器:
//All和Get接口属于文档v1
options.DocumentFilter<GroupNameDocumentFilter>(new object[] { "v1", new string[] { nameof(HomeController.Get) } });
//All和Post接口属于v2
options.DocumentFilter<GroupNameDocumentFilter>(new object[] { "v2", new string[] { nameof(HomeController.Post) } });
然后取消上面Get方法和Post方法的ApiExplorerSettings特性,这样实现的效果和上面直接使用ApiExplorerSettings特性修饰的效果是相似的。
这里说相似并非一致,是因为上面的GroupNameDocumentFilter是在第一次获取swagger.json时执行设置GroupName,也就是说第一次获取swagger.json会获取到所有的接口,所以一般也不会采用这种方法,而是采用上面介绍的使用IActionModelConvention和IControllerModelConvention来实现。
OperationFilter
什么是Operation?Operation可以简单的理解为一个操作,因为swagger是根据项目中的接口,自动生成接口文档,就自然需要对每个接口进行解析,接口路由是什么,接口需要什么参数,接口返回什么数据等等,而对每个接口的解析就可以视为一个Operation。
OperationFilter是操作过滤器,这个方法需要一个实现类IOperationFilter接口的类型,而它的第二个参数arguments是这个类型实例化时传入的参数。
OperationFilter允许我们对已经生成的接口进行修改,比如可以添加参数,修改参数类型等等。
需要注意的是,OperationFilter在获取swagger文档接口时调用,也就是请求swagger.json时调用,而且只对属于当前请求接口文档的接口进行过滤调用。
比如我们有一个Operation过滤器:
public class MyOperationFilter : IOperationFilter
string documentName;
public MyOperationFilter(string documentName)
this.documentName = documentName;
public void Apply(OpenApiOperation operation, OperationFilterContext context)
//过滤处理
接着调用SwaggerGenOptions的OperationFilter方法添加
options.OperationFilter<MyOperationFilter>(new object[] { "v1" });
上面的过滤器实例化需要一个参数documentName,所以在OperationFilter方法中有一个参数。
这个接口只会对当前请求的接口文档进行调用,也就是说,如果我们请求的是swagger文档v1,也就是请求/swagger/v1/swagger.json时,这个过滤器会对All方法和Get方法执行,如果请求的是swagger文档v2,也就是请求/swagger/v2/swagger.json时,这个过滤器会对All方法和Post方法进行调用。自定义的OperationFilter需要实现IOperationFilter的Apply接口方法,而Apply方法有两个参数:OpenApiOperation和OperationFilterContext,同样的,OpenApiOperation包含了和当前接口相关的信息,比如认证情况,所属的标签,还可以自定义的自己的Servers。而OperationFilterContext则包换了接口方法的的相关引用。
OperationFilter是用的比较多的方法了,比如上面的全局认证,因为直接调用AddSecurityRequirement添加的是全局认证,但是项目中可能部分接口不需要认证,这时我们就可以写一个OperationFilter对每一个接口进行判断了:
public class ResponsesOperationFilter : IOperationFilter
public void Apply(OpenApiOperation operation, OperationFilterContext context)
var authAttributes = context.MethodInfo.DeclaringType.GetCustomAttributes(true)
.Union(context.MethodInfo.GetCustomAttributes(true))
.OfType<AuthorizeAttribute>();
var list = new List<OpenApiSecurityRequirement>();
if (authAttributes.Any() && !context.MethodInfo.GetCustomAttributes(true).OfType<AllowAnonymousAttribute>().Any())
operation.Responses["401"] = new OpenApiResponse { Description = "Unauthorized" };
//operation.Responses.Add("403", new OpenApiResponse { Description = "Forbidden" });
//声明一个Scheme,注意下面的Id要和AddSecurityDefinition中的参数name一致
var scheme = new OpenApiSecurityScheme()
Reference = new OpenApiReference() { Type = ReferenceType.SecurityScheme, Id = "JwtBearer" }
//注册全局认证(所有的接口都可以使用认证)
operation.Security = new List<OpenApiSecurityRequirement>(){new OpenApiSecurityRequirement()
[scheme] = new string[0]
然后使用OperationFilter添加这个过滤器:
options.OperationFilter<ResponsesOperationFilter>();
现在可以测试一下了,我们将上面的All接口使用Authorize特性添加认证
/// <summary>
/// 未使用ApiExplorerSettings特性,表名属于每一个swagger文档
/// </summary>
/// <returns>结果</returns>
[HttpGet("All"), Authorize]
public string All()
return "All";
然后运行项目得到:
再比如,我们一般写接口,都会对返回的数据做一个规范,比如每个接口都会有响应代码,响应信息等等,而程序中我们是通过过滤器去实现的,所以接口都是直接返回数据,但是我们的swagger不知道,比如上面我们的测试接口返回的都是string类型,所以页面上也是展示string类型没错:
假如我们添加了过滤器对结果进行了一个处理,结果不在是string类型了,这个时候我们就可以使用OperationFilter做一个调整了:
public class MyOperationFilter : IOperationFilter
public void Apply(OpenApiOperation operation, OperationFilterContext context)
foreach (var key in operation.Responses.Keys)
var content = operation.Responses[key].Content;
foreach (var mediaTypeKey in content.Keys)
var mediaType = content[mediaTypeKey];
var schema = new OpenApiSchema();
schema.Type = "object";
schema.Properties = new Dictionary<string, OpenApiSchema>()
["code"] = new OpenApiSchema() { Type = "integer" },
["message"] = new OpenApiSchema() { Type = "string" },
["error"] = new OpenApiSchema()
Type = "object",
Properties = new Dictionary<string, OpenApiSchema>()
["message"] = new OpenApiSchema() { Type = "string" },
["stackTrace"] = new OpenApiSchema() { Type = "string" }
["result"] = mediaType.Schema
mediaType.Schema = schema;
记得使用OperationFilter添加过滤器:
options.OperationFilter<MyOperationFilter>();
显示效果如下:
RequestBodyFilter
RequestBody理所当然的就是请求体了,一般指的就是Post请求,RequestBodyFilter就是允许我们对请求体的信息作出调整,同样的,它是在获取Swagger.json文档时调用,而且只对那些有请求体的接口才会执行。
RequestBodyFilter的用法类似DocumentFilter和OperationFilter,一般也不会去修改请求体的默认行为,因为它可能导致请求失败,所以一般不常用,这里就不介绍了
ParameterFilter
Parameter指的是接口的参数,而ParameterFilter当然就是允许我们对参数的结构信息作出调整了,同样的,它是在获取Swagger.json文档时调用,而且只对那些参数的接口才会执行。
比如,我们有这么一个接口:
/// <summary>
/// 有参数接口
/// </summary>
/// <returns></returns>
[HttpGet("GetPara")]
public string GetPara(string para="default")
return $"para is {para},but para from header is {Request.Headers["para"]}";
然后我们可以使用ParameterFilter修改上面para参数在http请求中的位置,比如将它放在请求头中:
public class MyParameterFilter : IParameterFilter
public void Apply(OpenApiParameter parameter, ParameterFilterContext context)
if (context.ParameterInfo.Name == "para")
parameter.In = ParameterLocation.Header;
然后使用ParameterFilter方法添加过滤器:
options.ParameterFilter<MyParameterFilter>();
不过一般不会使用ParameterFilter去修改参数的默认行为,因为这可能会导致接口调用失败。
SchemaFilter
Schema指的是结构,一般指的是接口请求参数和响应返回的参数结构,比如我们想将所有的int类型换成string类型:
public class MySchemaFilter : ISchemaFilter
public void Apply(OpenApiSchema schema, SchemaFilterContext context)
if (context.Type == typeof(int))
schema.Type = "string";
假如有接口:
/// <summary>
/// 测试接口
/// </summary>
/// <returns></returns>
[HttpGet("Get")]
public int Get(int id)
return 1;
运行后所有的int参数在swaggerUI上都会显示为string 类型:
再比如,我们可以使用SchemaFilter来处理枚举类型注释的显示问题,举个例子:
比如我们有一个性别枚举类型:
public enum SexEnum
/// <summary>
/// 未知
/// </summary>
Unknown = 0,
/// <summary>
/// 男
/// </summary>
Male = 1,
/// <summary>
/// 女
/// </summary>
Female = 2
然后有个User类持有此枚举类型的一个属性:
public class User
/// <summary>
/// 用户Id
/// </summary>
public int Id { get; set; }
/// <summary>
/// 用户名称
/// </summary>
public string Name { get; set; }
/// <summary>
/// 用户性别
/// </summary>
public SexEnum Sex { get; set; }
如果将User类作为接口参数或者返回类型,比如有下面的接口:
/// <summary>
/// 获取一个用户信息
/// </summary>
/// <param name="userId">用户ID</param>
/// <returns>用户信息</returns>
[HttpGet("GetUserById")]
public User GetUserById(int userId)
return new User();
直接运行后得到的返回类型的说明是这样的:
这就有个问题了,枚举类型中的0、1、2等等就是何含义,这个没有在swagger中体现出来,这个时候我们可以通过SchemaFilter来修改Schema信息。
比如,可以先用一个特性(例如使用DescriptionAttribute)标识枚举类型的每一项,用于说明含义:
public enum SexEnum
/// <summary>
/// 未知
/// </summary>
[Description("未知")]
Unknown = 0,
/// <summary>
/// 男
/// </summary>
[Description("男")]
Male = 1,
/// <summary>
/// 女
/// </summary>
[Description("女")]
Female = 2
接着我们创建一个MySchemaFilter类,实现ISchemaFilter接口:
public class MySchemaFilter : ISchemaFilter
static readonly ConcurrentDictionary<Type, Tuple<string, object>[]> dict = new ConcurrentDictionary<Type, Tuple<string, object>[]>();
public void Apply(OpenApiSchema schema, SchemaFilterContext context)
if (context.Type.IsEnum)
var items = GetTextValueItems(context.Type);
if (items.Length > 0)
string decription = string.Join(",", items.Select(f => $"{f.Item1}={f.Item2}"));
schema.Description = string.IsNullOrEmpty(schema.Description) ? decription : $"{schema.Description}:{decription}";
else if (context.Type.IsClass && context.Type != typeof(string))
UpdateSchemaDescription(schema, context);
private void UpdateSchemaDescription(OpenApiSchema schema, SchemaFilterContext context)
if (schema.Reference!=null)
var s = context.SchemaRepository.Schemas[schema.Reference.Id];
if (s != null && s.Enum != null && s.Enum.Count > 0)
if (!string.IsNullOrEmpty(s.Description))
string description = $"【{s.Description}】";
if (string.IsNullOrEmpty(schema.Description) || !schema.Description.EndsWith(description))
schema.Description += description;
foreach (var key in schema.Properties.Keys)
var s = schema.Properties[key];
UpdateSchemaDescription(s, context);
/// <summary>
/// 获取枚举值+描述
/// </summary>
/// <param name="enumType"></param>
/// <returns></returns>
private Tuple<string, object>[] GetTextValueItems(Type enumType)
Tuple<string, object>[] tuples;
if (dict.TryGetValue(enumType, out tuples) && tuples != null)
return tuples;
FieldInfo[] fields = enumType.GetFields();
List<KeyValuePair<string, int>> list = new List<KeyValuePair<string, int>>();
foreach (FieldInfo field in fields)
if (field.FieldType.IsEnum)
var attribute = field.GetCustomAttribute<DescriptionAttribute>();
if (attribute == null)
continue;
string key = attribute?.Description ?? field.Name;
int value = ((int)enumType.InvokeMember(field.Name, BindingFlags.GetField, null, null, null));
if (string.IsNullOrEmpty(key))
continue;
list.Add(new KeyValuePair<string, int>(key, value));
tuples = list.OrderBy(f => f.Value).Select(f => new Tuple<string, object>(f.Key, f.Value.ToString())).ToArray();
dict.TryAdd(enumType, tuples);
return tuples;
MySchemaFilter
最后在Startup中使用
services.AddSwaggerGen(options =>
options.SchemaFilter<MySchemaFilter>();
再次运行项目后,得到的架构就有每个枚举项的属性了,当然,你也可以安装自己的意愿去生成特定格式的架构,这只是一个简单的例子
其他方法就不准备介绍了,比如:
DescribeAllEnumsAsStrings方法表示在将枚举类型解释成字符串名称而不是默认的整形数字
DescribeAllParametersInCamelCase方法表示将参数使用驼峰命名法处理
等等这些方法都用的比较少,而且这些都比较简单,感兴趣的可以看看源码学习
另外需要注意的是,在Swashbuckle.AspNetCore 6.0+以后的版本中,上面两个方法已经被移除了,作者希望我们通过.net core提供的依赖注入及JsonConverter机制自行去实现。
但是作者有提供了一个 Swashbuckle.AspNetCore.Newtonsoft 包,基于Newtonsoft.Json 来实现DescribeAllEnumsAsStrings,DescribeAllParametersInCamelCase 原来的这两个方法:
services.AddSwaggerGenNewtonsoftSupport();
services.Configure<MvcNewtonsoftJsonOptions>(options =>
//等价于原来的DescribeAllEnumsAsStrings方法
options.SerializerSettings.Converters.Add(new Newtonsoft.Json.Converters.StringEnumConverter());
//等价于原来的DescribeAllParametersInCamelCase方法
options.SerializerSettings.Converters.Add(new Newtonsoft.Json.Converters.StringEnumConverter(new Newtonsoft.Json.Serialization.CamelCaseNamingStrategy()));
特别注意的是,这样做是解决Swagger页面展示枚举类型时按字符串展示,但真实调用接口返回的格式还是需要自行实现JsonConverter。
毕竟Swagger只是接口说明文档,它不影响真实接口返回的数据信息,而.net core的MVC序列化有两种方案:Newtonsoft.Json和System.Text.Json,所以这也是预料之中的事。
三、添加Swagger中间件(UseSwagger,UseSwaggerUI)
细心地朋友应该注意到,在上面的例子中,添加Swagger中间件其实有两个,分别是UseSwagger和UseSwaggerUI两个方法:
UseSwagger:添加Swagger中间件,主要用于拦截swagger.json请求,从而可以获取返回所需的接口架构信息
UseSwaggerUI:添加SwaggerUI中间件,主要用于拦截swagger/index.html页面请求,返回页面给前端
整个swagger页面访问流程如下:
1、浏览器输入swaggerUI页面地址,比如:http://localhost:5000/swagger/index.html,这个地址是可配置的
2、请求被SwaggerUI中间件拦截,然后返回页面,这个页面是嵌入的资源文件,也可以设置成外部自己的页面文件(使用外部静态文件拦截)
3、页面接收到Swagger的Index页面后,会根据SwaggerUI中间件中使用SwaggerEndpoint方法设置的文档列表,加载第一个文档,也就是获取文档架构信息swagger.json
4、浏览器请求的swagger.json被Swagger中间件拦截,然后解析属于请求文档的所有接口,并最终返回一串json格式的数据
5、浏览器根据接收到的swagger,json数据呈现UI界面
UseSwagger方法有个包含SwaggerOptions的重载,UseSwaggerUI则有个包含SwaggerUIOptions的重载,两者相辅相成,所以这里在一起介绍这两个方法
SwaggerOptions
SwaggerOptions比较简单,就三个属性:
RouteTemplate
路由模板,默认值是/swagger/{documentName}/swagger.json,这个属性很重要!而且这个属性中必须包含{documentName}参数。
上面第3、4步骤已经说到,index.html页面会根据SwaggerUI中间件中使用SwaggerEndpoint方法设置的文档列表,然后使用第一个文档的路由发送一个GET请求,请求会被Swagger中间件中拦截,然后Swagger中间件中会使用RouteTemplate属性去匹配请求路径,然后得到documentName,也就是接口文档名,从而确定要返回哪些接口,所以,这个RouteTemplate一定要配合SwaggerEndpoint中的路由一起使用,要保证通过SwaggerEndpoint方法中的路由能找到documentName。
比如,如果将RouteTemplate设置成:
app.UseSwagger(options =>
options.RouteTemplate = "/{documentName}.json";
那么SwaggerEndpoint就得做出相应的调整:
app.UseSwaggerUI(options =>
options.SwaggerEndpoint("/v1.json", "v1");
options.SwaggerEndpoint("/v2.json", "v2");
当然,上面的SwaggerEndpoint方法中的路由可以添加虚拟路径,毕竟虚拟路径会在转发时被处理掉。
总之,这个属性很重要,尽可能不要修改,然后是上面默认的格式在SwaggerEndpoint方法中声明。
SerializeAsV2
表示按Swagger2.0格式序列化生成swagger.json,这个不推荐使用,尽可能的使用新版本的就可以了。
PreSerializeFilters
这个属性也是个过滤器,类似于上面介绍的DocumentFilter,在解析完所有接口后得到swaggerDocument之后调用执行,也就是在DocumentFilter,OperationFilter等过滤器之后调用执行。不建议使用这个属性,因为它能实现的功能使用DocumentFilter,OperationFilter等过滤器都能实现。
SwaggerUIOptions
SwaggerUIOptions则包含了SwaggerUI页面的一些设置,主要有六个属性:
RoutePrefix
设置SwaggerUI的Index页面的地址,默认是swagger,也就是说可以使用http://host:port/swagger可以访问到SwaggerUI页面,如果设置成空字符串,那么久可以使用http://host:port直接访问到SwaggerUI页面了
IndexStream
上面解释过,Swagger的UI页面是嵌入的资源文件,默认值是:
app.UseSwaggerUI(options =>
options.IndexStream = () => typeof(SwaggerUIOptions).GetTypeInfo().Assembly.GetManifestResourceStream("Swashbuckle.AspNetCore.SwaggerUI.index.html");
我们可以修改成自己的页面,比如Hello World:
app.UseSwaggerUI(options =>
options.IndexStream = () => new MemoryStream(Encoding.UTF8.GetBytes("Hello World"));
DocumentTitle
这个其实就是html页面的title
HeadContent
这个属性是往SwaggerUI页面head标签中添加我们自己的代码,比如引入一些样式文件,或者执行自己的一些脚本代码,比如:
app.UseSwaggerUI(options =>
options.HeadContent += $"<script type='text/javascript'>alert('欢迎来到SwaggerUI页面')</script>";
然后进入SwaggerUI就会弹出警告框了。
注意,上面的设置使用的是+=,而不是直接赋值。
但是一般时候,我们不是直接使用HeadConten属性的,而是使用 SwaggerUIOptions的两个拓展方法去实现:InjectStylesheet和InjectJavascript,这两个拓展方法主要是注入样式和javascript代码:
/// <summary>
/// Injects additional CSS stylesheets into the index.html page
/// </summary>
/// <param name="options"></param>
/// <param name="path">A path to the stylesheet - i.e. the link "href" attribute</param>
/// <param name="media">The target media - i.e. the link "media" attribute</param>
public static void InjectStylesheet(this SwaggerUIOptions options, string path, string media = "screen")
var builder = new StringBuilder(options.HeadContent);
builder.AppendLine($"<link href='{path}' rel='stylesheet' media='{media}' type='text/css' />");
options.HeadContent = builder.ToString();
/// <summary>
/// Injects additional Javascript files into the index.html page
/// </summary>
/// <param name="options"></param>
/// <param name="path">A path to the javascript - i.e. the script "src" attribute</param>
/// <param name="type">The script type - i.e. the script "type" attribute</param>
public static void InjectJavascript(this SwaggerUIOptions options, string path, string type = "text/javascript")
var builder = new StringBuilder(options.HeadContent);
builder.AppendLine($"<script src='{path}' type='{type}'></script>");
options.HeadContent = builder.ToString();
ConfigObject
其他配置对象,包括之前介绍的SwaggerDocument文档的地址等等。
OAuthConfigObject
和OAuth认证有关的配置信息,比如ClientId、ClientSecret等等。
对于ConfigObject,OAuthConfigObject两个对象,一般都不是直接使用它,而是用SwaggerUIOptions的拓展方法,比如之前一直介绍的SwaggerEndpoint方法,其实就是给ConfigObject的Urls属性增加对象:
/// <summary>
/// Adds Swagger JSON endpoints. Can be fully-qualified or relative to the UI page
/// </summary>
/// <param name="options"></param>
/// <param name="url">Can be fully qualified or relative to the current host</param>
/// <param name="name">The description that appears in the document selector drop-down</param>
public static void SwaggerEndpoint(this SwaggerUIOptions options, string url, string name)
var urls = new List<UrlDescriptor>(options.ConfigObject.Urls ?? Enumerable.Empty<UrlDescriptor>());
urls.Add(new UrlDescriptor { Url = url, Name = name} );
options.ConfigObject.Urls = urls;
到这里基本上就差不多了,写了这么多该收尾了。
主要就是记住三点:
1、服务注入使用AddSwaggerGen方法,主要就是生成接口相关信息,如认证,接口注释等等,还有几种过滤器帮助我们实现自己的需求
2、中间件注入有两个:UseSwagger和UseSwaggerUI:
UseSwagger负责返回接口架构信息,返回的是json格式的数据
UseSwaggerUI负责返回的是页面信息,返回的是html内容
3、如果涉及到接口生成的,尽可能在AddSwaggerGen中实现,如果涉及到UI页面的,尽可能在UseSwaggerUI中实现