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

 更新時間:2019年10月20日 10:41:57   作者: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 = "[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 效果

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

總結

以上就是這篇文章的全部內容了,希望本文的內容對大家的學習或者工作具有一定的參考學習價值,謝謝大家對腳本之家的支持。

相關文章

最新評論

福建体育彩票时时彩11