netcore3.0 webapi集成Swagger 5.0

在項目中引用Swashbuckle.AspNetCore和Swashbuckle.AspNetCore.Filters兩個dll，在Startup中的ConfigureServices相關配置代碼如下

            services.AddSwaggerGen(options =>
            {
                string contactName = Configuration.GetSection("SwaggerDoc:ContactName").Value;
                string contactNameEmail = Configuration.GetSection("SwaggerDoc:ContactEmail").Value;
                string contactUrl = Configuration.GetSection("SwaggerDoc:ContactUrl").Value;
                options.SwaggerDoc("v1", new OpenApiInfo
                {
                    Version = Configuration.GetSection("SwaggerDoc:Version").Value,
                    Title = Configuration.GetSection("SwaggerDoc:Title").Value,
                    Description = Configuration.GetSection("SwaggerDoc:Description").Value,
                    Contact = new OpenApiContact { Name = contactName, Email = contactNameEmail, Url =new Uri(contactUrl)},
                    License = new OpenApiLicense { Name = contactName, Url = new Uri(contactUrl) }
                });

                var basePath = PlatformServices.Default.Application.ApplicationBasePath;
                var xmlPath = Path.Combine(basePath, "Yuebon.WebApi.xml");
                options.IncludeXmlComments(xmlPath);
                options.DocumentFilter<HiddenApiFilter>(); // 在接口類、方法標記屬性 [HiddenApi]，可以阻止【Swagger文檔】生成
                options.OperationFilter<AddHeaderOperationFilter>("correlationId", "Correlation Id for the request", false); // adds any string you like to the request headers - in this case, a correlation id
                options.OperationFilter<AddResponseHeadersFilter>();
                options.OperationFilter<AppendAuthorizeToSummaryOperationFilter>();

                options.OperationFilter<SecurityRequirementsOperationFilter>();
                //給api添加token令牌證書
                options.AddSecurityDefinition("oauth2", new OpenApiSecurityScheme
                {
                    Description = "JWT授權(數據將在請求頭中進行傳輸) 直接在下框中輸入Bearer {token}（注意兩者之間是一個空格）\"",
                    Name = "Authorization",//jwt默認的參數名稱
                    In = ParameterLocation.Header,//jwt默認存放Authorization信息的位置(請求頭中)
                    Type = SecuritySchemeType.ApiKey
                });
            });

 兩個重點：

1、options.DocumentFilter<HiddenApiFilter>();定義那些接口方法被隱藏

2、啓用oauth2安全授權訪問api接口

                options.OperationFilter<SecurityRequirementsOperationFilter>();
                //給api添加token令牌證書
                options.AddSecurityDefinition("oauth2", new OpenApiSecurityScheme
                {
                    Description = "JWT授權(數據將在請求頭中進行傳輸) 直接在下框中輸入Bearer {token}（注意兩者之間是一個空格）\"",
                    Name = "Authorization",//jwt默認的參數名稱
                    In = ParameterLocation.Header,//jwt默認存放Authorization信息的位置(請求頭中)
                    Type = SecuritySchemeType.ApiKey
                });

其中使用SecurityRequirementsOperationFilter需要在控制器頭部加[Authorization]或則方法頭部加[Authorization]，如下：

 [Authorize]
 public class TokenController : ControllerBase

或者

[Authorize("Customer")]
public PersonResponse GetPerson([FromBody]PersonRequest personRequest)

這樣在每個接口纔會有小鎖出現。


更多介紹請參考https://github.com/domaindrivendev/Swashbuckle.AspNetCore和https://github.com/mattfrear/Swashbuckle.AspNetCore.Filters