咔叽游戏

 找回密码
 立即注册

QQ登录

只需一步,快速开始

搜索
查看: 575|回复: 0

[ASP.NET] asp.net core 3.0中使用swagger的方法与问题

[复制链接]
  • TA的每日心情
    无聊
    2019-5-27 08:20
  • 签到天数: 4 天

    [LV.2]圆转纯熟

    发表于 2020-2-28 17:13:15 | 显示全部楼层 |阅读模式
    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 效果
    asp.net core 3.0中使用swagger的方法与问题-1.jpg

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

    Memo#

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

      https://github.com/domaindrivendev/Swashbuckle.AspNetCore/tree/master/test/WebSites/MultipleVersions/Swaggerhttps://stackoverflow.com/questions/58197244/swaggerui-with-netcore-3-0-bearer-token-authorizationhttps://github.com/domaindrivendev/Swashbuckle.AspNetCore/issues/1295https://github.com/WeihanLi/SparkTodo
    总结
    以上就是这篇文章的全部内容了,希望本文的内容对大家的学习或者工作具有一定的参考学习价值,谢谢大家对咔叽网单www.2nzz.com的支持。

    QQ|免责声明|小黑屋|手机版|Archiver|咔叽游戏

    GMT+8, 2024-3-29 10:37

    Powered by Discuz! X3.4

    © 2001-2023 Discuz! Team.

    快速回复 返回顶部 返回列表