Intro#
上次更新了 asp.net core 3.0 簡單的記錄了一下 swagger 的使用，那個項目的 api 比較簡單，都是匿名接口不涉及到認證以及 api 版本控制，最近把另外一個 api 項目升級到了 3.0，還是遇到了一些問題，這里單獨寫一篇文章介紹，避免踩坑。
Swagger 基本使用#
swagger 服務注冊：
|
1
2
3
4
5
6
7
8
9
10
11
12
13
|
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); }); |
中間件配置：
|
1
2
3
4
5
6
7
8
9
10
|
//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 endpointapp.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 相關(guān)的 OperationFilter:
|
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
|
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); }} |
中間件配置：
|
1
2
3
4
5
6
7
8
9
10
11
|
//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 endpointapp.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
總結(jié)
以上就是這篇文章的全部內(nèi)容了，希望本文的內(nèi)容對大家的學習或者工作具有一定的參考學習價值，謝謝大家對服務器之家的支持。
原文鏈接：https://www.cnblogs.com/weihanli/p/ues-swagger-in-aspnetcore3_0.html
