震惊！Swagger的这些属性你都忽略了吗？

dotNET跨平台

于 2024-01-18 07:54:00 发布

阅读量141

点赞数

原文链接：https://mp.weixin.qq.com/s?__biz=MzAwNTMxMzg1MA==&mid=2654098757&idx=8&sn=141b503b99b960f64af9cc9be4a0d9f4&chksm=8121a5039ecff24b4cc9d43f50b77b3d52d87633728367c6987403640ec3f889eb976e4784a5&scene=126&sessionid=0

版权

本文介绍了在Swagger中如何启用永久授权、使用控制器XML注释、控制TryItOut请求的持续时间和文档展开方式，以及SwaggerUI的路由设置。重点讲解了OAuth2集成和自动化登录机制，是Swagger开发者必备的知识点。

摘要由CSDN通过智能技术生成

盘点一下在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();