asp.net core 3.0 中使用 swagger
阿新 • • 發佈：2019-10-18
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 = "[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