ds8-solution-pro/ds-wms-service/DS.Module.Swagger/SwaggerInstall.cs

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

namespace DS.Module.Swagger;

/// <summary>
/// Swagger 服务
/// </summary>
public static class SwaggerInstall
{
    public static IServiceCollection AddSwaggerInstall(this IServiceCollection services)
    {
        if (services == null) throw new ArgumentNullException(nameof(services));

        string url = AppSetting.Configuration["SwaggerDoc:ContactUrl"];
        var env = services.GetService<IWebHostEnvironment>();
        var basePath = AppContext.BaseDirectory;
        Console.WriteLine("基本路径" + basePath);
        services.AddMvcCore().AddApiExplorer();
        services.AddSwaggerGen(options =>
        {
            string contactName = AppSetting.Configuration["SwaggerDoc:ContactName"];
            string contactNameEmail = AppSetting.Configuration["SwaggerDoc:ContactEmail"];
            string contactUrl = AppSetting.Configuration["SwaggerDoc:ContactUrl"];
            options.SwaggerDoc(contactName, 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"); //这个就是Data层的xml文件名
                options.IncludeXmlComments(xmlModelPath);
            }
            catch (Exception ex)
            {
                throw new Exception("Api.xml和Data.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>();

            // 必须是 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" }
                }
            });
        });
        return services;
    }
}