Asp.netcoreSwashbuckleSwagger的常用配置

背景

我们发现很多⼩伙伴⽇常使⽤ Swashbuckle Swagger 都不看⽂档的，写下常需⽤到的配置/写法；基本使⽤

Package Manager : Install-Package Swashbuckle.AspNetCore记得⽤swagger⼀定要给action打[httpmehtod]标签[HttpGet]

public IEnumerable SearchProducts([FromQuery]string keywords)public static IServiceCollection AddSwagger(this IServiceCollection services){

services.AddSwaggerGen(c => {

c.SwaggerDoc(\"v1\ {

Version = \"v1\ Title = \"test api\ });

//多个xml⽂件

var xmlFile = $\"{Assembly.GetExecutingAssembly().GetName().Name}.xml\"; var xmlPath = Path.Combine(AppContext.BaseDirectory, xmlFile);

var dtoXmlPath = Path.Combine(AppContext.BaseDirectory, $\"{typeof(BaseIdEntity).Assembly.GetName().Name}.xml\"); c.IncludeXmlComments(xmlPath); c.IncludeXmlComments(dtoXmlPath); });

return services;}

public static IApplicationBuilder UseSwagger(this IApplicationBuilder app){

//配置⼆级⽬录

var basePath = \"/testapi\"; app.UseSwagger(c => {

c.PreSerializeFilters.Add((swaggerDoc, httpReq) => swaggerDoc.Servers = new List { new OpenApiServer { Url = $\"{basePath}\" } }); });

app.UseSwaggerUI(c => {

c.SwaggerEndpoint($\"{ basePath}/swagger/v1/swagger.json\ });

return app;}

多版本⽀持

services.AddSwaggerGen(c =>{

c.SwaggerDoc(\"v1\ c.SwaggerDoc(\"v2\})

[HttpPost]

[ApiExplorerSettings(GroupName = \"v2\")]public void Post([FromBody]Product product)更完善的枚举⽀持

Install-Package Unchase.Swashbuckle.AspNetCore.Extensionsservices.AddSwaggerGen(options => { //...

// or configured:

options.AddEnumsWithValuesFixFilters(services, o => {

// add schema filter to fix enums (add 'x-enumNames' for NSwag) in schema o.ApplySchemaFilter = true;

// add parameter filter to fix enums (add 'x-enumNames' for NSwag) in schema parameters o.ApplyParameterFilter = true;

// add document filter to fix enums displaying in swagger document o.ApplyDocumentFilter = true;

// add descriptions from DescriptionAttribute or xml-comments to fix enums (add 'x-enumDescriptions' for schema extensions) for applied filters o.IncludeDescriptions = true;

// add remarks for descriptions from xml-comments o.IncludeXEnumRemarks = true;

// get descriptions from DescriptionAttribute then from xml-comments

o.DescriptionSource = DescriptionSources.DescriptionAttributesThenXmlComments;

// get descriptions from xml-file comments on the specified path // should use \"options.IncludeXmlComments(xmlFilePath);\" before o.IncludeXmlCommentsFrom(xmlFilePath); // the same for another xml-files... }); });

枚举⽂档效果

OAuth2.0⽀持

Install-Package Swashbuckle.AspNetCore.Filters⼿填AccessToken(apikey)⽅式 services.AddSwaggerGen(c => {

//...

c.OperationFilter();

c.AddSecurityDefinition(\"oauth2\ {

Description = \"Standard Authorization header using the Bearer scheme. Example: \\\"bearer {token}\\\"\ In = ParameterLocation.Header, Name = \"Authorization\

Type = SecuritySchemeType.ApiKey }); });效果

引导跳转OAuth服务器⽅式

services.AddSwaggerGen(c => {

//...

c.OperationFilter();

c.AddSecurityDefinition(\"oauth2\ {

Type = SecuritySchemeType.OAuth2, Flows = new OpenApiOAuthFlows() {

Implicit = new OpenApiOAuthFlow() {

AuthorizationUrl = new Uri(\"https://your.identityserver.io/connect/authorize\"), Scopes = new Dictionary {

{ \"testapi.rw\授权访问测试TestApi\" } } } } });

});

app.UseSwaggerUI(c =>{

//...

c.OAuthClientId(\"test_swaager\");});效果

忽略某个Api[HttpGet(\"{id}\")]

[ApiExplorerSettings(IgnoreApi = true)]public Product GetById(int id)修改传输数据类型

services.AddSwaggerGen(c => {

//long类型转string

c.MapType(() => new OpenApiSchema { Type = \"string\" }); });

⾃定义描述（标签）

Install-Package Swashbuckle.AspNetCore.Annotations[SwaggerTag(\"Create, read, update and delete Products\")]public class ProductsController{ ...}

Quer请求参数⼩驼峰

public class QueryBillDto {

///

public string Query { get; set; } ///

public EApp? Appid { get; set; }

///

public EnumBillType? BillType { get; set; } ///

public DateTime? BillBegin { get; set; }

///

public DateTime? BillEnd { get; set; } } ...

//⽐如定义了这样的接⼝

public async Task GetBillList([FromQuery] QueryBillDto dto) {

return Ok(); }

swagger-ui需要显⽰ 为⼩写的这样： services.AddSwaggerGen(c => {

//参数描述⼩驼峰

o.DescribeAllParametersInCamelCase(); });