當前位置 主頁 > 網站技術 > 代碼類 > 最大化 縮小

    asp.net core 3.0中使用swagger的方法與問題

    欄目:代碼類 時間:2019-10-20 15:06

    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);
     }
    }
    
在线观看中文字幕理论片