asp.net core 3.0 中使用 swagger
asp.net core 3.0 中使用 swagger
Intro
上次更新了 asp.net core 3.0 简单的记录了一下 swagger 的使用 ,详细可以参考asp.net core3.0更新简记,那个项目的 api 比较简单,都是匿名接口不涉及到认证以及 api 版本控制,最近把另外一个 api 项目升级到了 3.0,还是遇到了一些问题,这里单独写一篇文章介绍,避免踩坑。
Swagger 基本使用
安装 nuget 包 Swashbuckle.AspNetCore
,需要使用 5.0.x 版本,使用最新的 5.0.0-rc 版本(还没发稳定版,需要显示预览版本才能看到)
swagger 服务注册:
services.AddSwaggerGen(option =>
{
option.SwaggerDoc("sparktodo", new OpenApiInfo
{
Version = "v1",
Title = "SparkTodo API",
Description = "API for SparkTodo",
Contact = new OpenApiContact() { Name = "WeihanLi", Email = "weihanli@outlook.com" }
});
// 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
上面的配置来自 https://github.com/WeihanLi/SparkTodo 这个项目,要获取代码可以参考这个项目
Reference
- https://github.com/domaindrivendev/Swashbuckle.AspNetCore/tree/master/test/WebSites/MultipleVersions/Swagger
- https://stackoverflow.com/questions/58197244/swaggerui-with-netcore-3-0-bearer-token-authorization
- https://github.com/domaindrivendev/Swashbuckle.AspNetCore/issues/1295
- https://github.com/WeihanLi/SparkTodo
asp.net core 3.0 中使用 swagger的更多相关文章
- ASP.NET Core 1.0 中使用 Swagger 生成文档
github:https://github.com/domaindrivendev/Ahoy 之前文章有介绍在ASP.NET WebAPI 中使用Swagger生成文档,ASP.NET Core 1. ...
- 在ASP.NET Core 3.0中使用Swagger
1.使用NuGet安装以下依赖: Swashbuckle.AspNetCore 注:版本选最高版本的,我选 5.0 rc4 2.在ConfigureServices添加以下代码 services.Ad ...
- ASP.NET Core Web API中使用Swagger
本节导航 Swagger介绍 在ASP.NET CORE 中的使用swagger 在软件开发中,管理和测试API是一件重要而富有挑战性的工作.在我之前的文章<研发团队,请管好你的API文档& ...
- ASP.NET Core 1.0 中的依赖项管理
var appInsights=window.appInsights||function(config){ function r(config){t[config]=function(){var i= ...
- 在ASP.NET Core 1.0中如何发送邮件
(此文章同时发表在本人微信公众号"dotNET每日精华文章",欢迎右边二维码来关注.) 题记:目前.NET Core 1.0中并没有提供SMTP相关的类库,那么要如何从ASP.NE ...
- 用ASP.NET Core 1.0中实现邮件发送功能
准备将一些项目迁移到 asp.net core 先从封装类库入手,在遇到邮件发送类时发现在 asp.net core 1.0中并示提供SMTP相关类库,于是网上一搜发现了MailKit 好东西一定要试 ...
- 在ASP.NET Core 2.0中使用CookieAuthentication
在ASP.NET Core中关于Security有两个容易混淆的概念一个是Authentication(认证),一个是Authorization(授权).而前者是确定用户是谁的过程,后者是围绕着他们允 ...
- 如何在ASP.NET Core 2.0中使用Razor页面
如何在ASP.NET Core 2.0中使用Razor页面 DotNetCore2017-11-22 14:49 问题 如何在ASP.NET Core 2.0中使用Razor页面 解 创建一个空的项 ...
- ASP.NET Core 3.0中使用动态控制器路由
原文:Dynamic controller routing in ASP.NET Core 3.0 作者:Filip W 译文:https://www.cnblogs.com/lwqlun/p/114 ...
随机推荐
- 从“HDU 2005 第几天?”谈起
在程序设计中,日期时间的处理经常会遇到.在C语言程序设计的一些教材中会出现如下例子或习题. [例1]第几天? (HDU 2005) 给定一个日期,输出这个日期是该年的第几天. Input输入数据有多组 ...
- Ubuntu系统添加用户权限
一.首先创建一个新用户: sudo adduser hadoop 其次设置密码: sudo passwd hadoop 如果无法使用root密码,请输入如下命令: sudo passwd root 二 ...
- webhook 自动部署代码
前话: 一般情况,自己在本地开发,代码改动后要push放到线上去看效果,但是我们还要到线上环境手动拉取代码库 git pull 下来, 一来一回太麻烦了. 现在用webhook就可以实现本地开发,pu ...
- .NET Core 3.0 Preview 9 发布
翻译自官方博客 今天,我们宣布推出.NET Core 3.0 Preview 9.就像预览版8一样,我们专注打磨最终版本的.NET Core 3.0,而不是添加新功能.如果这些最终版本看起来不像早期预 ...
- 4.String、StringBuffer、StringBuilder
一.String类型 String类型是一个引用类型,但是该类被final修饰,属于最终类,不能派生子类. 字符串一旦初始化就不能再被更改,因为String类中存储内容的char[]数组是也被fina ...
- kubernetes部署jenkins(Docker in Docker)及认证
引言 Jenkins是一款开源 CI&CD 软件,用于自动化各种任务,包括构建.测试和部署软件. 本文将Jenkins的master与slave置于Pod中,部署在namespace:jenk ...
- php异或计算绕过preg_match()
原理以制作免杀马为例: 在制作免杀马的过程,根据php的语言特性对字符进行!运算会将字符类型转为bool类型,而bool类型遇到运算符号时,true会自动转为数字1,false会自动转为数字0 ...
- MySQL单标查询
一 单表查询的语法 #查询数据的本质:mysql会到你本地的硬盘上找到对应的文件,然后打开文件,按照你的查询条件来找出你需要的数据.下面是完整的一个单表查询的语法 select * from,这个se ...
- TestNG(十五)xml文件实现多线程测试
package com.course.testng.thread; import org.testng.annotations.Test; public class ThreadOnXml { @Te ...
- 解决ie6上碰到的css兼容问题
ie6上css碰到的坑 前两天在给一个项目做东西的时候,碰到一个有意思的项目,是需要兼容ie6,有一些碰到并且解决的问题,给大家写下来,方便大家以后碰到类似的问题哈- 喜欢的话还请点赞! 1.impo ...