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

asp.net core 3.0中使用swagger的方法与问题
 更新时间：2019年10月20日 10:41:56   作者：WeihanLi  

这篇文章主要给大家介绍了关于asp.net core 3.0中使用swagger的方法与遇到的一些问题，文中通过示例代码介绍的非常详细，对大家的学习或者使用asp.net core 3.0具有一定的参考学习价值，需要的朋友们下面来一起学习学习吧

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 = “[email protected]” }
});

// 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 认证#

services.AddSwaggerGen(option =>
{
// …

// Add security definitions
option.AddSecurityDefinition(“Bearer”, new OpenApiSecurityScheme()
{
Description = “Please enter into field the word ‘Bearer’ followed by a space and the JWT value”,
Name = “Authorization”,
In = ParameterLocation.Header,
Type = SecuritySchemeType.ApiKey,
});
option.AddSecurityRequirement(new OpenApiSecurityRequirement
{
{ new OpenApiSecurityScheme
{
Reference = new OpenApiReference()
{
Id = “Bearer”,
Type = ReferenceType.SecurityScheme
}
}, Array.Empty<string>() }
});
});

支持多个 ApiVersion#

services.AddApiVersioning(options =>
{
options.AssumeDefaultVersionWhenUnspecified = true;
options.DefaultApiVersion = ApiVersion.Default;
options.ReportApiVersions = true;
});

services.AddSwaggerGen(option =>
{
// …

option.SwaggerDoc(“v1”, new OpenApiInfo { Version = “v1”, Title = “API V1” });
option.SwaggerDoc(“v2”, new OpenApiInfo { Version = “v2”, Title = “API V2″ });

option.DocInclusionPredicate((docName, apiDesc) =>
{
var versions = apiDesc.CustomAttributes()
.OfType<ApiVersionAttribute>()
.SelectMany(attr => attr.Versions);

return versions.Any(v => $”v{v.ToString()}” == docName);
});

option.OperationFilter<RemoveVersionParameterOperationFilter>();
option.DocumentFilter<SetVersionInPathDocumentFilter>();
});

自定义 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#

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

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

总结
以上就是这篇文章的全部内容了，希望本文的内容对大家的学习或者工作具有一定的参考学习价值，谢谢大家对华域联盟的支持。

您可能感兴趣的文章:Asp.net core WebApi 使用Swagger生成帮助页实例.Net Core2.1 WebAPI新增Swagger插件详解.NET Core利用swagger进行API接口文档管理的方法详解Asp.Net Core WebAPI使用Swagger时API隐藏和分组详解记Asp.Net Core Swagger使用并带域接口处理的方法

asp.net
core3.0
swagger

相关文章
asp.net下生成英文字符数字验证码的代码用了asp.net随机数,获取指定位数的字母或数字以后，进行图片输出的验证码函数。 2009-12-12
Asp.net内置对象之Cookies(简介/属性方法/基本操作及实例)本文将围绕cookies了解Cookies对象/Cookie对象的属性和方法/Cookie的基本操作及实例:Cookie的写入和读取/Cookie对象相比Session、Application的优缺点扥等，感兴趣的朋友可以了解下，或许对你学习cookies有所帮助 2013-02-02
VS2010发布Web网站技术攻略本篇文章主要包含了完整的发布网站步骤、发布网站过程中可能遇到的问题，以及配套的解决方法，相信感兴趣的朋友一定会喜欢这篇文章的
2015-07-07
ASP.NET Core3.1 Ocelot认证的实现这篇文章主要介绍了ASP.NET Core3.1 Ocelot认证的实现，文中通过示例代码介绍的非常详细，对大家的学习或者工作具有一定的参考学习价值，需要的朋友们下面随着小编来一起学习学习吧 2020-11-11
ASP.NET Core使用GraphQL第二章之中间件这篇文章主要给大家介绍了关于ASP.NET Core使用GraphQL第二章之中间件的相关资料，文中通过示例代码介绍的非常详细，对大家的学习或者工作具有一定的参考学习价值，需要的朋友们下面随着小编来一起学习学习吧 2018-11-11
在.NET中扫描局域网服务的实现方法下面小编就为大家分享一篇在.NET中扫描局域网服务的实现方法，具有很好的参考价值，希望对大家有所帮助。一起跟随小编过来看看吧 2018-01-01
asp.net(C#)中给控件添加客户端js事件的方法今天做一个输入界面，有一需求根据一个DropDownList选择不同,后面部分出现不同的输入界面，若把响应事件放在服务端去做，得频繁刷页面。就想放在客户来处理显示和隐藏相应的输入界面。
2010-03-03
asp.net中几种常用的身份验证方法总结本篇文章小编就为大家介绍一下在asp.net中几种常用的身份验证方法。需要的朋友可以过来参考下，希望对大家有所帮助 2013-11-11
.net core 读取本地指定目录下的文件的实例代码这篇文章主要介绍了.net core 读取本地指定目录下的文件的实例代码，非常不错，具有一定的参考借鉴价值 ,需要的朋友可以参考下 2018-09-09
注册或者点击按钮时,怎么防止用户重复提交数据(实例讲解)这篇文章主要是对注册或者点击按钮时,怎么防止用户重复提交数据进行了介绍，需要的朋友可以过来参考下，希望对大家有所帮助 2013-12-12

最新评论