asp.net core 3.0中使用swagger的方法与问题

Intro#

上次更新了 asp.net core 3.0 简单的记录了一下 swagger 的使用，那个项目的 api 比较简单，都是匿名接口不涉及到认证以及 api 版本控制，最近把另外一个 api 项目升级到了 3.0，还是遇到了一些问题，这里单独写一篇文章介绍，避免踩坑。

Swagger 基本使用#

swagger 服务注册：

services.AddSwaggerGen(option =>
 {
 option.SwaggerDoc("sparktodo", new OpenApiInfo
 {
  Version = "v1",
  Title = "SparkTodo API",
  Description = "API for SparkTodo",
  Contact = new OpenApiContact() { Name = "WeihanLi", Email = "[e-mail]" }
 });

 // include document file
 option.IncludeXmlComments(Path.Combine(AppContext.BaseDirectory, $"{typeof(Startup).Assembly.GetName().Name}.xml"), true);
 });

中间件配置：

//Enable middleware to serve generated Swagger as a JSON endpoint.
app.UseSwagger();
//Enable middleware to serve swagger-ui (HTML, JS, CSS etc.), specifying the Swagger JSON endpoint
app.UseSwaggerUI(option =>
{
 option.SwaggerEndpoint("/swagger/sparktodo/swagger.json", "sparktodo Docs");

 option.RoutePrefix = string.Empty;
 option.DocumentTitle = "SparkTodo API";
});

为 Swagger 添加 Bearer Token 认证#

1. services.AddSwaggerGen(option => 
2. { 
3.  // ... 
4.  
5.  // Add security definitions 
6.  option.AddSecurityDefinition("Bearer", new OpenApiSecurityScheme() 
7.  { 
8.  Description = "Please enter into field the word 'Bearer' followed by a space and the JWT value", 
9.  Name = "Authorization", 
10.  In = ParameterLocation.Header, 
11.  Type = SecuritySchemeType.ApiKey, 
12.  }); 
13.  option.AddSecurityRequirement(new OpenApiSecurityRequirement 
14.  { 
15.  { new OpenApiSecurityScheme 
16.  { 
17.   Reference = new OpenApiReference() 
18.   { 
19.   Id = "Bearer", 
20.   Type = ReferenceType.SecurityScheme 
21.   } 
22.  }, Array.Empty<string>() } 
23.  }); 
24. }); 

支持多个 ApiVersion#

1. services.AddApiVersioning(options => 
2.  { 
3.  options.AssumeDefaultVersionWhenUnspecified = true; 
4.  options.DefaultApiVersion = ApiVersion.Default; 
5.  options.ReportApiVersions = true; 
6.  }); 
7.  
8. services.AddSwaggerGen(option => 
9. { 
10.  // ... 
11.  
12.  option.SwaggerDoc("v1", new OpenApiInfo { Version = "v1", Title = "API V1" }); 
13.  option.SwaggerDoc("v2", new OpenApiInfo { Version = "v2", Title = "API V2" }); 
14.  
15.  option.DocInclusionPredicate((docName, apiDesc) => 
16.  { 
17.  var versions = apiDesc.CustomAttributes() 
18.   .OfType<ApiVersionAttribute>() 
19.   .SelectMany(attr => attr.Versions); 
20.  
21.  return versions.Any(v => $"v{v.ToString()}" == docName); 
22.  }); 
23.  
24.  option.OperationFilter<RemoveVersionParameterOperationFilter>(); 
25.  option.DocumentFilter<SetVersionInPathDocumentFilter>(); 
26. }); 

 

自定义 Api version 相关的 OperationFilter:

public class SetVersionInPathDocumentFilter : IDocumentFilter
{
 public void Apply(OpenApiDocument swaggerDoc, DocumentFilterContext context)
 {
 var updatedPaths = new OpenApiPaths();

 foreach (var entry in swaggerDoc.Paths)
 {
  updatedPaths.Add(
  entry.Key.Replace("v{version}", swaggerDoc.Info.Version),
  entry.Value);
 }

 swaggerDoc.Paths = updatedPaths;
 }
}

public class RemoveVersionParameterOperationFilter : IOperationFilter
{
 public void Apply(OpenApiOperation operation, OperationFilterContext context)
 {
 // Remove version parameter from all Operations
 var versionParameter = operation.Parameters.Single(p => p.Name == "version");
 operation.Parameters.Remove(versionParameter);
 }
}

中间件配置：

//Enable middleware to serve generated Swagger as a JSON endpoint.
app.UseSwagger();
//Enable middleware to serve swagger-ui (HTML, JS, CSS etc.), specifying the Swagger JSON endpoint
app.UseSwaggerUI(option =>
{
 option.SwaggerEndpoint("/swagger/v2/swagger.json", "V2 Docs");
 option.SwaggerEndpoint("/swagger/v1/swagger.json", "V1 Docs");

 option.RoutePrefix = string.Empty;
 option.DocumentTitle = "SparkTodo API";
});

最终 swagger 效果

Memo#

上面的配置来自 https://github.com/WeihanLi/SparkTodo 这个项目，要获取代码可以参考这个项目

Reference#

• https://github.com/domaindrivendev/Swashbuckle.AspNetCore/tree/master/test/WebSites/MultipleVersions/Swagger
• https://*.com/questions/58197244/swaggerui-with-netcore-3-0-bearer-token-authorization
• https://github.com/domaindrivendev/Swashbuckle.AspNetCore/issues/1295
• https://github.com/WeihanLi/SparkTodo

总结

以上就是这篇文章的全部内容了，希望本文的内容对大家的学习或者工作具有一定的参考学习价值，谢谢大家对服务器之家的支持。

原文链接：https://www.cnblogs.com/weihanli/p/ues-swagger-in-aspnetcore3_0.html