AspcoreSwashbuckleSwagger的常⽤配置
背景
我们发现很多⼩伙伴⽇常使⽤ Swashbuckle Swagger 都不看⽂档的，写下常需⽤到的配置/写法；
基本使⽤
Package Manager : Install-Package Swashbuckle.AspNetCore
记得⽤swagger⼀定要给action打[httpmehtod]标签
[HttpGet]
public IEnumerable<Product> SearchProducts([FromQuery]string keywords)
public static IServiceCollection AddSwagger(this IServiceCollection services)
{
services.AddSwaggerGen(c =>
{
c.SwaggerDoc("v1", new OpenApiInfo
{
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<OpenApiServer> { new OpenApiServer { Url = $"{basePath}" } });    });
app.UseSwaggerUI(c =>
{
c.SwaggerEndpoint($"{ basePath}/swagger/v1/swagger.json", "FitnessApi V1");
});
return app;
}
多版本⽀持
services.AddSwaggerGen(c =>
{
c.SwaggerDoc("v1", new OpenApiInfo { Title = "My API - V1", Version = "v1" });
c.SwaggerDoc("v2", new OpenApiInfo { Title = "My API - V2", Version = "v2" });
})
[HttpPost]
[ApiExplorerSettings(GroupName = "v2")]
public void Post([FromBody]Product product)
更完善的枚举⽀持
Install-Package Unchase.Swashbuckle.AspNetCore.Extensions
services.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
});
});
枚举⽂档效果
OAuth2.0⽀持
Install-Package Swashbuckle.AspNetCore.Filters
⼿填AccessToken(apikey)⽅式
services.AddSwaggerGen(c =>
{
//...
c.OperationFilter<SecurityRequirementsOperationFilter>();
c.AddSecurityDefinition("oauth2", new OpenApiSecurityScheme
{
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<SecurityRequirementsOperationFilter>();
c.AddSecurityDefinition("oauth2", new OpenApiSecurityScheme
{
Type = SecuritySchemeType.OAuth2,
Flows = new OpenApiOAuthFlows()
{
Implicit = new OpenApiOAuthFlow()
{
AuthorizationUrl = new Uri("your.identityserver.io/connect/authorize"),
Scopes = new Dictionary<string, string>
{
{ "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<long>(() => new OpenApiSchema { Type = "string" });
});
⾃定义描述（标签）
Install-Package Swashbuckle.AspNetCore.Annotations
[SwaggerTag("Create, read, update and delete Products")]
public class ProductsController
{
.
..
}
Quer请求参数⼩驼峰
public class QueryBillDto
{
/// <summary>
/// PID/⼿机号/昵称
/// </summary>
public string Query { get; set; }
/// <summary>asp查看源码配置ui
///
/
// </summary>
public EApp? Appid { get; set; }
/// <summary>
/// 收⼊/⽀出类型
/// </summary>
public EnumBillType? BillType { get; set; }
/// <summary>
/// 账单起始⽇期
/// </summary>
public DateTime? BillBegin { get; set; }
/// <summary>
/
// 账单截⽌⽇期
/// </summary>
public DateTime? BillEnd { get; set; }
}
...
//⽐如定义了这样的接⼝
public async Task<IActionResult> GetBillList([FromQuery] QueryBillDto dto)  {
return Ok();
}
swagger-ui需要显⽰为⼩写的这样：
services.AddSwaggerGen(c =>
{
//参数描述⼩驼峰
o.DescribeAllParametersInCamelCase();
});

版权声明：本站内容均来自互联网，仅供演示用，请勿用于商业和其他非法用途。如果侵犯了您的权益请与我们联系QQ:729038198，我们将在24小时内删除。