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

asp.net core 3.0 中使用 swagger的更多相关文章

  1. ASP.NET Core 1.0 中使用 Swagger 生成文档

    github:https://github.com/domaindrivendev/Ahoy 之前文章有介绍在ASP.NET WebAPI 中使用Swagger生成文档,ASP.NET Core 1. ...

  2. 在ASP.NET Core 3.0中使用Swagger

    1.使用NuGet安装以下依赖: Swashbuckle.AspNetCore 注:版本选最高版本的,我选 5.0 rc4 2.在ConfigureServices添加以下代码 services.Ad ...

  3. ASP.NET Core Web API中使用Swagger

    本节导航 Swagger介绍 在ASP.NET CORE 中的使用swagger   在软件开发中,管理和测试API是一件重要而富有挑战性的工作.在我之前的文章<研发团队,请管好你的API文档& ...

  4. ASP.NET Core 1.0 中的依赖项管理

    var appInsights=window.appInsights||function(config){ function r(config){t[config]=function(){var i= ...

  5. 在ASP.NET Core 1.0中如何发送邮件

    (此文章同时发表在本人微信公众号"dotNET每日精华文章",欢迎右边二维码来关注.) 题记:目前.NET Core 1.0中并没有提供SMTP相关的类库,那么要如何从ASP.NE ...

  6. 用ASP.NET Core 1.0中实现邮件发送功能

    准备将一些项目迁移到 asp.net core 先从封装类库入手,在遇到邮件发送类时发现在 asp.net core 1.0中并示提供SMTP相关类库,于是网上一搜发现了MailKit 好东西一定要试 ...

  7. 在ASP.NET Core 2.0中使用CookieAuthentication

    在ASP.NET Core中关于Security有两个容易混淆的概念一个是Authentication(认证),一个是Authorization(授权).而前者是确定用户是谁的过程,后者是围绕着他们允 ...

  8. 如何在ASP.NET Core 2.0中使用Razor页面

    如何在ASP.NET Core 2.0中使用Razor页面  DotNetCore2017-11-22 14:49 问题 如何在ASP.NET Core 2.0中使用Razor页面 解 创建一个空的项 ...

  9. ASP.NET Core 3.0中使用动态控制器路由

    原文:Dynamic controller routing in ASP.NET Core 3.0 作者:Filip W 译文:https://www.cnblogs.com/lwqlun/p/114 ...

随机推荐

  1. lambda表达式排序

    lambda表达式排序简洁 1.给一个字符串数组: String[] atp = {"2016-06-28 08:00:00", "2017-12-05 19:17:32 ...

  2. 解决The mysql extension is deprecated and will be removed

    今天打开网站突然发现报错:“PHP Deprecated:  mysql_connect(): The mysql extension is deprecated and will be remove ...

  3. Redis集群的离线安装以及原理理解

    一.本文主要是记录一下Redis集群在linux系统下离线的安装步骤,毕竟在生产环境下一般都是无法联网的,Redis的集群的Ruby环境安装过程还是很麻烦的,涉及到很多的依赖的安装,所以写了一个文章来 ...

  4. Spotlight on Oracle注册码破解(亲测可用)

    了解到该工具监控十分强大,该工具优点: 我就是为了监控一个Oracle数据库,查阅各种资料,真是费了十牛二虎之力,才破解完成.#_# 在客户端安装好了,连接监控的服务器,提示得要注册码,这外国的软件基 ...

  5. android 屏幕切换

    1.将Activity固定位竖屏可以在配置文件这么写 <activity android:screenOrientation="portrait"> 横屏显示: < ...

  6. 浮动后的 <li> 如何在 <ul> 中居中显示?

    百度了许久都没有满意的解决方案,现在终于搞定了. 其实,只要 ul 的父元素 css 样式设了 text-align: center; 然后 ul 设了 display: inline-block; ...

  7. JDBC连接时出现的问题总结

    java.sql.SQLException: The server time zone value '�й���׼ʱ��' is unrecognized or represents more tha ...

  8. 控制执行流程之switch语句

    switch语句,同时也是一种选择性语句,其根据整数表达式的值(整数选择因子)选择一段代码去执行.整数选择因子为int类型或者char类型.

  9. Salesforce学习之路-developer篇(二)利用Jenkins和Bitbucket实现Salesforce的CI/CD功能

    上文提到,基于CRM的二次开发是必不可少的,但是在实际项目中CI/CD是不可忽略的一个重要部分,与传统的Java,Python项目不同,如果对Salesforce进行持续集成和持续部署呢? 结合找到的 ...

  10. BOM之window核心模块

    Window对象包含以下五大核心:document,screen,navigator,history,location. 一     document 文档 document包含了浏览器对标准DOM实 ...