ASP.NET Core 在 Swagger UI 中显示自定义的 Header Token

本文介绍如何在Swagger UI中添加AuthToken参数到Header中,通过创建自定义的过滤器类并配置Swagger,使得API文档更加完善。

摘要生成于 C知道 ,由 DeepSeek-R1 满血版支持, 前往体验 >

Swagger 是个好东西,对于前后端分离的网站来说,不仅是提高前后端开发人员沟通效率的利器,也大大方便了后端人员测试 API。有时候,API 中可能需要在 Header 中设置认证参数,比如 authToken,这样的功能我们通常是使用 ActionFilter 实现的,这就会导致 swagger UI 中缺少 authToken 字段,下面就来介绍解决这个问题的办法。

创建一个过滤器类,内容如下:

/// <summary>
/// this class is for swagger to generate AuthToken Header filed on swagger UI
/// </summary>
public class AddAuthTokenHeaderParameter : IOperationFilter{  

 
public void Apply(Operation operation, OperationFilterContext context)    
{        

      if (operation.Parameters == null)            operation.Parameters = new List<IParameter>();    
      
var attrs = context.ApiDescription.GetActionAttributes();  
      
foreach (var attr in attrs)        {            // 如果 Attribute 是我们自定义的验证过滤器            if (attr.GetType() == typeof(Auth))            {                operation.Parameters.Add(new NonBodyParameter()                {                    Name = "AuthToken",                    In = "header",                    Type = "string",                    Required = false                });            }        }    } }

然后在配置 Swagger 的地方,做一些修改:

services.AddSwaggerGen(c =>
            {           
      c.SingleApiVersion(new Info()                {            
                Version = "v1",          
                Title = "API 文档",                
                Description = "系统的 API 文档"                });          
       c.OperationFilter<AddAuthTokenHeaderParameter>(); // 手动高亮            });

最后,dotnet run

frameborder="0" scrolling="no" style="font-family: inherit; border-width: initial; border-style: none; font-style: inherit; font-variant: inherit; font-weight: inherit; font-stretch: inherit; font-size: inherit; line-height: inherit; vertical-align: baseline; width: 835px; height: 257px;">

这样,Swagger UI 中就显示了附加在 header 中的参数——AuthToken,还要啥 Postman。

相关文章: 

原文地址:http://www.cnblogs.com/JacZhu/p/6188968.html


.NET社区新闻,深度好文,微信中搜索dotNET跨平台或扫描二维码关注

.NET 6中使用Swashbuckle.AspNetCore生成的Swagger UI,方法注释通常会在API文档的左侧展示。如果你想要将注释显示在右侧,这通常不会直接在Swagger UI的标准布局中实现,因为默认情况下它是按照标准的RESTful风格设计的,注释会集中在一个单独的区域解释各个操作。 不过,你可以通过自定义渲染模板(Customize the Display of Operations)来达到类似的效果。首先,你需要创建一个自定义的`JsonDocumentationProvider`,然后在`OperationFilter<T>`中处理并提取注解信息,最后在HTML模板中重新组织内容。以下是大致步骤: 1. 安装必要的NuGet包: ```bash dotnet add package Swashbuckle.AspNetCore.Filters dotnet add package Swashbuckle.AspNetCore.SwaggerGen ``` 2. 创建自定义的`JsonDocumentationProvider`: ```csharp public class CustomJsonDocumentationProvider : JsonDocumentationProvider { public override OpenApiDocument Read(string json) { var document = base.Read(json); // 自定义解析过程,这里仅作为示例,你需要实际提取和整理注释信息 foreach (var api in document.Paths.Values) { api.Description = ExtractDescription(api); // 或者使用其他方式获取注释 } return document; } private string ExtractDescription(ApiDescription api) { // 从你的操作描述、注解或其他源中获取描述 return api.ActionDescriptor.GetMethodInfo()?.HelpPageDisplayInfo?.Summary; } } ``` 3. 注册你的`CustomJsonDocumentationProvider`: ```csharp services.AddSwaggerGen(options => { options.DocumentationProvider = new CustomJsonDocumentationProvider(); // 其他配置... }); ``` 4. 如果你想在HTML模板中更改布局,可以参考Swashbuckle的文档或查找相关的开源项目来做进一步定制。通常这涉及到修改`swagger-ui-bundle.js`中的样式和布局代码。 注意,这种方法可能会影响页面的整体结构和可维护性,因此最好在开发环境使用,并确保对最终部署的影响有限。
评论
添加红包

请填写红包祝福语或标题

红包个数最小为10个

红包金额最低5元

当前余额3.43前往充值 >
需支付:10.00
成就一亿技术人!
领取后你会自动成为博主和红包主的粉丝 规则
hope_wisdom
发出的红包
实付
使用余额支付
点击重新获取
扫码支付
钱包余额 0

抵扣说明:

1.余额是钱包充值的虚拟货币,按照1:1的比例进行支付金额的抵扣。
2.余额无法直接购买下载,可以购买VIP、付费专栏及课程。

余额充值