Asp.net core Swashbuckle Swagger 的常用配置

背景

　　.net core Swashbuckle Swagger 官方文档：https://github.com/domaindrivendev/Swashbuckle.AspNetCore

我们发现很多小伙伴日常使用 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;
}

注意：这里要先启用xml生成

#在项目csproj文件里启用这个
  <PropertyGroup>
    <GenerateDocumentationFile>True</GenerateDocumentationFile>
  </PropertyGroup>

或者到 项目 -> 属性启用：

配置二级目录

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 another xml-files...
        });
    });

枚举文档效果

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("https://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>
        /// 
        /// </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();
 });