swagger怎么在asp.net core 3.0项目中使用

tangjin

作者

本篇文章给大家分享的是有关swagger怎么在asp.net core 3.0项目中使用，小编觉得挺实用的，因此分享给大家学习，希望大家阅读完这篇文章后可以有所收获，话不多说，跟着小编一起来看看吧。

Swagger 基本使用#

swagger 服务注册：

services.AddSwaggerGen(option=>
{
option.SwaggerDoc("sparktodo",newOpenApiInfo
{
Version="v1",
Title="SparkTodoAPI",
Description="APIforSparkTodo",
Contact=newOpenApiContact(){Name="WeihanLi",Email="weihanli@outlook.com"}
});

//includedocumentfile
option.IncludeXmlComments(Path.Combine(AppContext.BaseDirectory,$"{typeof(Startup).Assembly.GetName().Name}.xml"),true);
});

中间件配置：

//EnablemiddlewaretoservegeneratedSwaggerasaJSONendpoint.
app.UseSwagger();
//Enablemiddlewaretoserveswagger-ui(HTML,JS,CSSetc.),specifyingtheSwaggerJSONendpoint
app.UseSwaggerUI(option=>
{
option.SwaggerEndpoint("/swagger/sparktodo/swagger.json","sparktodoDocs");

option.RoutePrefix=string.Empty;
option.DocumentTitle="SparkTodoAPI";
});

为 Swagger 添加 Bearer Token 认证#

services.AddSwaggerGen(option=>
{
//...

//Addsecuritydefinitions
option.AddSecurityDefinition("Bearer",newOpenApiSecurityScheme()
{
Description="Pleaseenterintofieldtheword'Bearer'followedbyaspaceandtheJWTvalue",
Name="Authorization",
In=ParameterLocation.Header,
Type=SecuritySchemeType.ApiKey,
});
option.AddSecurityRequirement(newOpenApiSecurityRequirement
{
{newOpenApiSecurityScheme
{
Reference=newOpenApiReference()
{
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",newOpenApiInfo{Version="v1",Title="APIV1"});
option.SwaggerDoc("v2",newOpenApiInfo{Version="v2",Title="APIV2"});

option.DocInclusionPredicate((docName,apiDesc)=>
{
varversions=apiDesc.CustomAttributes()
.OfType<ApiVersionAttribute>()
.SelectMany(attr=>attr.Versions);

returnversions.Any(v=>$"v{v.ToString()}"==docName);
});

option.OperationFilter<RemoveVersionParameterOperationFilter>();
option.DocumentFilter<SetVersionInPathDocumentFilter>();
});

自定义 Api version 相关的 OperationFilter:

publicclassSetVersionInPathDocumentFilter:IDocumentFilter
{
publicvoidApply(OpenApiDocumentswaggerDoc,DocumentFilterContextcontext)
{
varupdatedPaths=newOpenApiPaths();

foreach(varentryinswaggerDoc.Paths)
{
updatedPaths.Add(
entry.Key.Replace("v{version}",swaggerDoc.Info.Version),
entry.Value);
}

swaggerDoc.Paths=updatedPaths;
}
}

publicclassRemoveVersionParameterOperationFilter:IOperationFilter
{
publicvoidApply(OpenApiOperationoperation,OperationFilterContextcontext)
{
//RemoveversionparameterfromallOperations
varversionParameter=operation.Parameters.Single(p=>p.Name=="version");
operation.Parameters.Remove(versionParameter);
}
}

中间件配置：

//EnablemiddlewaretoservegeneratedSwaggerasaJSONendpoint.
app.UseSwagger();
//Enablemiddlewaretoserveswagger-ui(HTML,JS,CSSetc.),specifyingtheSwaggerJSONendpoint
app.UseSwaggerUI(option=>
{
option.SwaggerEndpoint("/swagger/v2/swagger.json","V2Docs");
option.SwaggerEndpoint("/swagger/v1/swagger.json","V1Docs");

option.RoutePrefix=string.Empty;
option.DocumentTitle="SparkTodoAPI";
});

最终 swagger 效果