526互联

.Net6 扩展Swagger

发布时间 2023-10-26 15:44:15作者: 糯米白白

.Net6 扩展Swagger

net6集成了swagger的基础功能，但功能不够用

因此只能自定义扩展方法了，如下

1、集成Jwt授权

将

builder.Services.AddSwaggerGen();

改成

builder.Services.AddSwaggerGen(c =>
{ 
    var scheme = new OpenApiSecurityScheme()
    {
        Description = "Authorization header. \r\nExample: 'Bearer abcdefxxx'",
        Reference = new OpenApiReference
        {
            Type = ReferenceType.SecurityScheme,
            Id = "Authorization"
        },
        Scheme = "oauth2",
        Name = "Authorization",
        In = ParameterLocation.Header,
        Type = SecuritySchemeType.ApiKey,  
    };
    c.AddSecurityDefinition("Authorization", scheme);
    var requirement = new OpenApiSecurityRequirement();
    requirement[scheme] = new List<string>();
    c.AddSecurityRequirement(requirement); 
});

2、增加Swagger注释

增加swagger注释后，测试人员/前段开发人员就可以自己看文档了

2.1、设置Model层和Api层项目XML输出

代码如下：

img

builder.Services.AddSwaggerGen(c =>
{
    var basePath = Path.GetDirectoryName(AppContext.BaseDirectory);
    //c.IncludeXmlComments(Path.Combine(basePath, Assembly.GetExecutingAssembly().GetName().Name+".xml"), true);
    c.IncludeXmlComments(Path.Combine(basePath, "swap.xml"), true);
    c.IncludeXmlComments(Path.Combine(basePath, "swapModels.xml"), true);

    //
    var scheme = new OpenApiSecurityScheme()
    {
        Description = "Authorization header. \r\nExample: 'Bearer 12345abcdef'",
        Reference = new OpenApiReference
        {
            Type = ReferenceType.SecurityScheme,
            Id = "Authorization"
        },
        Scheme = "oauth2",
        Name = "Authorization",
        In = ParameterLocation.Header,
        Type = SecuritySchemeType.ApiKey,  
    };
    c.AddSecurityDefinition("Authorization", scheme);
    var requirement = new OpenApiSecurityRequirement();
    requirement[scheme] = new List<string>();
    c.AddSecurityRequirement(requirement); 
});

3、自定义属性隐藏及Api方法隐藏

3.1、Api层新建swagger过滤器

using Microsoft.OpenApi.Models;
using swapCommon;//HiddenFieldAttribute 和 HiddenAttribute 在公共类库存 
using Swashbuckle.AspNetCore.SwaggerGen;
using System;
using System.Collections.Generic;
using System.Linq;
using System.Net.Http;
using System.Reflection;
using System.Text; 

namespace swapInit
{ 
    public class HiddenApiFilter : IDocumentFilter
    {
        public void Apply(OpenApiDocument swaggerDoc, DocumentFilterContext context)
        {
            foreach (var item in context.ApiDescriptions)
            {
                if (item.TryGetMethodInfo(out MethodInfo methodInfo))
                {
                    if (methodInfo.ReflectedType.CustomAttributes.Any(t => t.AttributeType == typeof(HiddenAttribute))
                    || methodInfo.CustomAttributes.Any(t => t.AttributeType == typeof(HiddenAttribute)))
                    {
                        var key = "/" + item.RelativePath.TrimEnd('/');
                        if (key.Contains("?"))
                        {
                            int idx = key.IndexOf("?", StringComparison.Ordinal);
                            key = key.Substring(0, idx);
                        }
                        if (swaggerDoc.Paths.ContainsKey(key))
                        {
                            swaggerDoc.Paths.Remove(key);
                        }
                    }
                }
            }
        }
    }


    public class HiddenFieldFilter : ISchemaFilter
    {
        public void Apply(OpenApiSchema schema, SchemaFilterContext context)
        {
            if (schema?.Properties == null)
            {
                return;
            }
            var name = context.Type.FullName;
            var excludedProperties = context.Type.GetProperties();
            foreach (var property in excludedProperties)
            {
                var attribute = property.GetCustomAttribute<HiddenFieldAttribute>();
                if (attribute != null
                    && schema.Properties.ContainsKey(ToLowerStart(property.Name)))
                {
                    schema.Properties.Remove(ToLowerStart(property.Name));
                }
            };
        }
        public static string ToLowerStart( string source)
        {
            if (string.IsNullOrWhiteSpace(source))
            {
                return source;
            }
            var start = source.Substring(0, 1);
            return $"{start.ToLower()}{source.Substring(1, source.Length - 1)}";
        }
    } 
}

3.2、公共类库层新建属性类

using System;
using System.Collections.Generic;
using System.Text;

namespace swapCommon
{
    [AttributeUsage(AttributeTargets.Property)]
    public class HiddenFieldAttribute : Attribute
    {
    }

    [AttributeUsage(AttributeTargets.Method | AttributeTargets.Class)]
    public class HiddenAttribute : Attribute
    {
    }
}

3.3、引用上述过滤器

img

builder.Services.AddSwaggerGen(c =>
{
    var basePath = Path.GetDirectoryName(AppContext.BaseDirectory);
    //c.IncludeXmlComments(Path.Combine(basePath, Assembly.GetExecutingAssembly().GetName().Name+".xml"), true);
    c.IncludeXmlComments(Path.Combine(basePath, "swap.xml"), true);
    c.IncludeXmlComments(Path.Combine(basePath, "swapModels.xml"), true);
    //
    c.DocumentFilter<HiddenApiFilter>(); 
    c.SchemaFilter<HiddenFieldFilter>();
    //
    var scheme = new OpenApiSecurityScheme()
    {
        Description = "Authorization header. \r\nExample: 'Bearer 12345abcdef'",
        Reference = new OpenApiReference
        {
            Type = ReferenceType.SecurityScheme,
            Id = "Authorization"
        },
        Scheme = "oauth2",
        Name = "Authorization",
        In = ParameterLocation.Header,
        Type = SecuritySchemeType.ApiKey,  
    };
    c.AddSecurityDefinition("Authorization", scheme);
    var requirement = new OpenApiSecurityRequirement();
    requirement[scheme] = new List<string>();
    c.AddSecurityRequirement(requirement); 
});

3.4、测试Swagger过滤器

3.4.1、定义一个Post方法

        /// <summary>
        /// 演示字段隐藏
        /// </summary>
        /// <param name="stdto"></param>
        /// <returns></returns>
        [HttpPost]
        [Route("GetStdto")] 
        public IActionResult GetStdto([FromBody]stdto stdto)
        {
            var dt = DateTime.Now;
            return Ok(dt );
        }

3.4.2、定义参数实体

有了身份证号，可以自动计算出年龄等场景

    public class stdto
    {
        public string name { get; set; }
        public string IdCard { get; set; }
        /// <summary>
        /// 该字段会在swagger中隐藏
        /// </summary>
        [HiddenField]
        public int age { get; set; }
    }

3.5、[Hidden]隐藏 Action 方法

不想让测试或前端在swagger上看到某方法，那就隐藏

        /// <summary>
        /// 演示Api隐藏 ，该方法不会展示在swagger上
        /// </summary>
        /// <param name="Hs">https://www.cnblogs.com/catcher1994/p/responsecaching.html</param>
        /// <returns></returns>
        [HttpGet]
        [Hidden]
        [Route("GetTime")] 
        public IActionResult GetTime()
        {
            var dt = DateTime.Now;
            return Ok(dt);
        }

4、规定项目时间返回格式

4.1、公共类库层先建JsonResult格式化类

 using System;
using System.Collections.Generic;
using System.Linq;
using System.Text;
using System.Text.Json; 
using System.Text.Json.Serialization;

namespace swapCommon.Ext
{
    public class JsonOptionsExt : JsonConverter<DateTime>
    {
        private readonly string Format;
        public JsonOptionsExt(string format = "yyyy-MM-dd HH:mm:ss")
        {
            Format = format;
        }
        public override void Write(Utf8JsonWriter writer, DateTime date, JsonSerializerOptions options)
        {
            writer.WriteStringValue(date.ToString(Format));
        }
        public override DateTime Read(ref Utf8JsonReader reader, Type typeToConvert, JsonSerializerOptions options)
        {
            // 获取时间类型的字符串
            var dt = reader.GetString();
            if (!string.IsNullOrEmpty(dt))
            {
                //将日期与时间之间的"T"替换为一个空格，将结尾的"Z"去掉，否则会报错
                dt = dt.Replace("T", " ").Replace("Z", "");
                //取到秒，毫秒内容也要去掉，经过测试，不去掉会报错
                if (dt.Length > 19)
                {
                    dt = dt.Substring(0, 19);
                }
                return DateTime.ParseExact(dt, Format, null);
            }
            return DateTime.Now;
        }
    }
}

4.2、添加控制器时引用

builder.Services.AddControllers()

改成

builder.Services.AddControllers().AddJsonOptions(options =>
{
    //时间格式化响应
    options.JsonSerializerOptions.Converters.Add(new JsonOptionsExt());
});

改好后，时间的返回就统一了

img

4.3、补充

关于时间格式为 "yyyy-MM-dd HH:mm:ss" 也可以不使用自定义的JsonOptionsExt

添加Nutget引用，Microsoft.AspNetCore.Mvc.NewtonsoftJson V6.0.6

AddControllers()代码段替换为：

builder.Services.AddControllers().AddNewtonsoftJson(options =>
{
    options.SerializerSettings.DateFormatString = "yyyy-MM-dd HH:mm:ss";
    options.SerializerSettings.ContractResolver = new DefaultContractResolver();
});

其中

options.SerializerSettings.ContractResolver = new DefaultContractResolver(); /*支持接收JOBject动态参数*/

JOBject 动态参数，例如

        [AllowAnonymous]
        [HttpPost]
        [Route("TestAlter")]
        public IActionResult TestAlter([FromBody] JObject data)
        { 
            return Ok(data);
        }

可接受任意json