YardBookSolution/yardbookapi-service/DS.Module.Swagger/SwaggerModule.cs

using System.Reflection;
using DS.Module.Core;
using DS.Module.Core.Extensions;
using DS.Module.Core.Modules;
using Microsoft.AspNetCore.Builder;
using Microsoft.AspNetCore.Hosting;
using Microsoft.Extensions.DependencyInjection;
using Microsoft.OpenApi.Models;
using Swashbuckle.AspNetCore.Filters;
using Swashbuckle.AspNetCore.SwaggerGen;

namespace DS.Module.Swagger;

public class SwaggerModule : DSAppModule
{
    public override void ConfigureServices(ConfigureServicesContext context)
    {
        var service = context.Services;
        string url = AppSetting.Configuration["SwaggerDoc:ContactUrl"];
        var env = context.Services.GetService<IWebHostEnvironment>();
        var basePath = env.ContentRootPath;
        service.AddMvcCore().AddApiExplorer();
        service.AddSwaggerGen(options =>
        {
            string contactName = AppSetting.Configuration["SwaggerDoc:ContactName"];
            string contactNameEmail = AppSetting.Configuration["SwaggerDoc:ContactEmail"];
            string contactUrl = AppSetting.Configuration["SwaggerDoc:ContactUrl"];
            options.SwaggerDoc("v1", new OpenApiInfo
            {
                Version = AppSetting.Configuration["SwaggerDoc:Version"],
                Title = AppSetting.Configuration["SwaggerDoc:Title"],
                Description = AppSetting.Configuration["SwaggerDoc:Description"],
                Contact = new OpenApiContact
                    { Name = contactName, Email = contactNameEmail, Url = new Uri(contactUrl) },
                License = new OpenApiLicense { Name = contactName, Url = new Uri(contactUrl) }
            });


            try
            {
                //就是这里
                var xmlPath = Path.Combine(basePath, "Api.xml"); //这个就是刚刚配置的xml文件名
                options.IncludeXmlComments(xmlPath, true); //默认的第二个参数是false，这个是controller的注释，记得修改

                var xmlModelPath = Path.Combine(basePath, "Data.xml"); //这个就是Model层的xml文件名
                options.IncludeXmlComments(xmlModelPath);
            }
            catch (Exception ex)
            {
                throw new Exception("Api.xml和Model.xml 丢失，请检查并拷贝。\n" + ex.Message);
            }

            options.CustomOperationIds(api =>
            {
                return api.TryGetMethodInfo(out MethodInfo methodInfo) ? methodInfo.Name : null;
            });
            // 一定要返回true！
            options.DocInclusionPredicate((docName, description) => { return true; });
            // 开启加权小锁
            options.OperationFilter<AddResponseHeadersFilter>();
            options.OperationFilter<AppendAuthorizeToSummaryOperationFilter>(); 
            // 在header中添加token，传递到后台
            options.OperationFilter<SecurityRequirementsOperationFilter>();
            // options.AddSecurityDefinition("oauth2", new OpenApiSecurityScheme
            // {
            //     Description = "JWT授权(数据将在请求头中进行传输) 直接在下框中输入Bearer {token}（注意两者之间是一个空格）\"",
            //     Name = "Authorization", //jwt默认的参数名称
            //     In = ParameterLocation.Header, //jwt默认存放Authorization信息的位置(请求头中)
            //     Type = SecuritySchemeType.ApiKey,
            //     Scheme = "Bearer",
            // });
            // options.AddSecurityRequirement(new OpenApiSecurityRequirement
            // {
            //     {
            //         new OpenApiSecurityScheme
            //             { Reference = new OpenApiReference { Type = ReferenceType.SecurityScheme, Id = "oauth2" } },
            //         new[] { "readAccess", "writeAccess" }
            //     }
            // });

            // 必须是 Bearer
            options.AddSecurityDefinition("oauth2", new OpenApiSecurityScheme
            {
                Description = "JWT授权(数据将在请求头中进行传输) 直接在下框中输入Bearer {token}（注意两者之间是一个空格）\"",
                Name = "Authorization", //jwt默认的参数名称
                In = ParameterLocation.Header, //jwt默认存放Authorization信息的位置(请求头中)
                Type = SecuritySchemeType.ApiKey,
                // BearerFormat = "JWT", //标识承载令牌的格式 该信息主要是出于文档目的
                Scheme = "Bearer" //授权中要使用的HTTP授权方案的名称
            });
            //在Heder中添加Token 传递到后台
            options.AddSecurityRequirement(new OpenApiSecurityRequirement
            {
                {
                    new OpenApiSecurityScheme
                    {
                        Reference = new OpenApiReference
                        {
                            Type = ReferenceType.SecurityScheme,
                            Id = "oauth2"
                        }
                    },
                    new string[] { "readAccess", "writeAccess" }
                }
            });
        });
    }

    public override void ApplicationInitialization(ApplicationContext context)
    {
        var app = context.GetApplicationBuilder();

        app.UseSwagger();
        app.UseSwaggerUI(c =>
        {
            c.SwaggerEndpoint("/swagger/v1/swagger.json", AppSetting.Configuration["SwaggerDoc:Version"]);
        });
    }
}