盘点一下在swagger中一些有用且经常忽略的属性

震惊！，这些Swagger的属性你都了解吗？

盘点一下在swagger中一些有用且经常忽略的属性

启用永久授权EnablePersistAuthorization

                app.UseSwaggerUI(c =>
                {
                    //指定Swagger JSON文件的终结点，用于加载和显示API文档。
                    //需要提供JSON文件的URL和一个可识别的名称
                    c.SwaggerEndpoint("/swagger/v1/swagger.json", "My API V1");
                   
                    //启用永久授权
                    c.EnablePersistAuthorization(); 
                });

启用后，在登陆的小锁输入token之后，就可以 避免每次重新调试，再次输入token的问题，原理是swagger里面调用js代码来实现每次自动登录的

控制器XML注释

在实现xml注入的时候， options.IncludeXmlComments(xml,true); ,第二个属性控制是否为控控制器添加注释

    public static class SwaggerSetup
    {
        public static IServiceCollection AddSwaggerSetup(this IServiceCollection services)
        { 

            // 默认配置
            Action<SwaggerGenOptions> defaultSetupAction = options =>
            {
                var basePath = AppContext.BaseDirectory;

                options.SwaggerDoc("v1",
                    new OpenApiInfo
                    {
                        Title = "在线接口文档",
                        Version = "v1"
                    });

                // 获取根目录下，所有 xml 完整路径（注：并不会获取二级目录下的文件）
                var directoryInfo = new DirectoryInfo(basePath);
                List<string> xmls = directoryInfo
                    .GetFiles()
                    .Where(f => f.Name.ToLower().EndsWith(".xml"))
                    .Select(f => f.FullName)
                    .ToList();

                // 添加注释文档
                foreach (var xml in xmls)
                {
                    options.IncludeXmlComments(xml,true);
                }

                //tode 将默认扩展状态设置为 "none"  

                // 开启加权小锁
                //options.OperationFilter<AuthenticationOperationFilter>();

                // 开启加权小锁
                //用于在 Swagger UI 的每个操作中添加 x-auth-token 响应头，以便在调用 API 后显示 token
                //options.OperationFilter<AddResponseHeadersFilter>();
                ////用于将 "Authorize" 字符串添加到 Swagger UI 中每个操作的标题中，提醒用户该操作需要认证/授权才能访问
                //options.OperationFilter<AppendAuthorizeToSummaryOperationFilter>();

                //// 在 Swagger UI 的每个操作中添加一个 "Authorization" 按钮，并将认证令牌包含在请求头中
                //options.OperationFilter<SecurityRequirementsOperationFilter>();

                // 接入 Jwt 认证
                //options.AddSecurityDefinition("Bearer", new OpenApiSecurityScheme
                {
                    Scheme = "Bearer",
                    BearerFormat = "JWT",
                    Description = "在下面输入框输入Token",
                    Name = "Authorization",
                    In = ParameterLocation.Header,
                    Type = SecuritySchemeType.Http
                });


            };

            // 注册 Swagger 并添加默认配置
            services.AddSwaggerGen(defaultSetupAction);

            // 如果有自定义配置
            //if (setupAction != null) services.Configure(setupAction);

            return services;
        }

    }

控制Try It Out请求的请求持续时间（以毫秒为单位）的显示

                app.UseSwaggerUI(c =>
                {
                    //指定Swagger JSON文件的终结点，用于加载和显示API文档。
                    //需要提供JSON文件的URL和一个可识别的名称
                    c.SwaggerEndpoint("/swagger/v1/swagger.json", "My API V1");
                    
                   //控制Try It Out请求的请求持续时间（以毫秒为单位）的显示
                    c.DisplayRequestDuration();
                });

swagger ui的路由

                app.UseSwaggerUI(c =>
                {
                    //指定Swagger JSON文件的终结点，用于加载和显示API文档。
                    //需要提供JSON文件的URL和一个可识别的名称
                    c.SwaggerEndpoint("/swagger/v1/swagger.json", "My API V1");
                    
                   //指定swagger文档的启动目录 。默认为swagger
                   //可以通过设置为空字符串来让Swagger UI直接在根路径下进行访问
                   //c.RoutePrefix = string.Empty;

                });

文档展开的方式

   //设置默认的接口文档展开方式，可选值包括None、List和Full。
   //默认值为None，表示不展开接口文档；
   //List表示只展开接口列表；
   //Full表示展开所有接口详情
   c.DocExpansion(DocExpansion.None); // 设置为完整模式 
   c.DisplayRequestDuration();
   c.EnablePersistAuthorization();