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 = "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 MVC+Bootstrap搭建个人博客之打造清新分页Helper(三)

    利用ASP.NET MVC+Bootstrap搭建个人博客之打造清新分页Helper(三)

    这篇文章主要介绍了利用ASP.NET MVC+Bootstrap搭建个人博客之打造清新分页Helper(三)的相关资料,非常不错,具有参考借鉴价值,需要的朋友可以参考下
    2016-06-06
  • c#生成缩略图不失真的方法实例分享

    c#生成缩略图不失真的方法实例分享

    使用.net的方法GetThumbnailImage生成的缩略图失真严重,这里推荐一种不失真生成缩略图的方法
    2013-12-12
  • Asp.net调试的一些问题小结

    Asp.net调试的一些问题小结

    这篇文章主要介绍了asp.net调试方便的知识点,在CSDN找了一些相关的解决方法,不敢独享,供大家相互学习交流之用
    2013-11-11
  • Windows虚拟主机与VPS如何实现301重定向(asp.net)

    Windows虚拟主机与VPS如何实现301重定向(asp.net)

    301重定向应该是研究SEO必须掌握的技术。如果你是刚接触SEO的菜鸟,想了解什么是301重定向,请看《html实现301重定向的方法》一文,我在该篇随笔中引用了Google网站站长工具对301重定向的解释
    2011-12-12
  • .net GridView分页模板的实例代码

    .net GridView分页模板的实例代码

    .net GridView分页模板的实例代码,对分页代码有兴趣的朋友可以参考一下
    2013-03-03
  • asp.net core webapi 服务端配置跨域的实例

    asp.net core webapi 服务端配置跨域的实例

    下面小编就为大家分享一篇asp.net core webapi 服务端配置跨域的实例,具有很好的参考价值,希望对大家有所帮助。一起跟随小编过来看看吧
    2017-12-12
  • ABP引入Dapper框架的创建使用

    ABP引入Dapper框架的创建使用

    这篇文章主要为大家介绍了ABP引入Dapper框架的创建使用,有需要的朋友可以借鉴参考下,希望能够有所帮助,祝大家多多进步,早日升职加薪
    2022-04-04
  • ASP.net百度主动推送功能实现代码

    ASP.net百度主动推送功能实现代码

    百度站长工具的主动推送功能,以最为快速的提交方式,推荐您将站点当天新产出链接立即通过此方式推送给百度,以保证新链接可以及时被百度收录
    2020-09-09
  • .NET Core 反射底层原理解析

    .NET Core 反射底层原理解析

    本文介绍了.NET中的反射机制,包括前期绑定(EarlyBinding)和后期绑定(LateBinding)的概念,反射是一种强大的工具,但在性能要求较高的场景中应谨慎使用,感兴趣的朋友跟随小编一起看看吧
    2024-11-11
  • .NET Core Web APi类库内嵌运行的方法

    .NET Core Web APi类库内嵌运行的方法

    这篇文章主要介绍了.NET Core Web APi类库内嵌运行的方法,本节我们重点讨论如何内嵌运行.NET Core Web APi类库,同时介绍了两种激活比如控制器特性方案,需要的朋友可以参考下
    2022-09-09

最新评论