asp.net core 3.0 中使用 swagger
程序员文章站
2023-10-28 23:34:10
asp.net core 3.0 中使用 swagger Intro 上次更新了 asp.net core 3.0 简单的记录了一下 swagger 的使用,那个项目的 api 比较简单,都是匿名接口不涉及到认证以及 api 版本控制,最近把另外一个 api 项目升级到了 3.0,还是遇到了一些问题 ......
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 = "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 一个中小型项目实战的起手式——Swagger配置
-
ASP.Net Core中使用枚举类而不是枚举的方法
-
Asp.net Core中如何使用中间件来管理websocket
-
ASP.NET Core应用中与第三方IoC/DI框架的整合
-
ASP.NET Core部署前期准备 使用Hyper-V安装Ubuntu Server 16.10
-
.net core webapi 文件上传在 Swagger 文档中的有好提示处理
-
创建基于ASP.NET core 3.1 的RazorPagesMovie项目(一)-创建和使用默认的模板
-
使用NuGet将我们的ASP.NET Core类库打包并将程序包(类库)发布到NuGet平台上进行管理
-
使用ASP.NET Core 3.x 构建 RESTful API - 5.1 输入验证
-
详解ASP.NET Core应用中如何记录和查看日志