CloudYxt.Api 4.1.2

云享通.Net Core针对WEBAPI常规操作库

一个常见的Startup.cs的Swagger相关定义示例

public void ConfigureServices(IServiceCollection services)
{
    //使用NewtonsoftJson加载API接口
    services.AddControllers().AddNewtonsoftJson((opt) =>
    {
        //json字符串大小写原样输出
        opt.SerializerSettings.ContractResolver = new Newtonsoft.Json.Serialization.DefaultContractResolver();
    });

    //设置接收文件长度的最大值。
    services.Configure<Microsoft.AspNetCore.Http.Features.FormOptions>(x =>
    {
        x.ValueLengthLimit = int.MaxValue;
        x.MultipartBodyLengthLimit = int.MaxValue;
        x.MultipartHeadersLengthLimit = int.MaxValue;
        x.MultipartBoundaryLengthLimit = int.MaxValue;
    });

    //全局拦截模型错误
    services.Configure<ApiBehaviorOptions>(options =>
    {
        options.InvalidModelStateResponseFactory = ApiHelperExtend.ApiMessageInvalidModelState;
    });

    services.AddSwaggerGen(c =>
    {
        c.SwaggerDoc("CloudYxtTestApi", new OpenApiInfo()
        {
            Title = "CloudYxtTestApi",
            Version = "v2",
            Description = "Api测试",
        });

        //类似JWT的认证模型
        c.AddSecurityDefinition("Authorization", new Microsoft.OpenApi.Models.OpenApiSecurityScheme()
        {
            Description = "在下框中输入请求头中需要添加授权信息，格式：“{协议版本} {token}”（注意两者之间是一个空格）",
            Name = "Authorization",
            In = Microsoft.OpenApi.Models.ParameterLocation.Header,
            Type = Microsoft.OpenApi.Models.SecuritySchemeType.ApiKey
        });

        //加载ApiMessageAuthorization认证的过滤器(当方法含有ApiMessageAuthorization时才出现锁)
        c.OperationFilter<ApiMessageAuthorizationSwaggerFilter>("Authorization");
        //使用DescriptionAttribute作为Description说明
        c.UseDescriptionAttributeAsTagDescription();

        //属性名称使用模型的完整名称
        //c.CustomSchemaIds(type => type.FullName); 
        //仅显示属性名称
        //c.SchemaFilter<PropertyOnlySchemaFilter>();

        //加载目录下的xml注释文件
        var xmlfiles = new DirectoryInfo(AppContext.BaseDirectory).GetFiles("*.xml");
        foreach (var file in xmlfiles)
            c.IncludeXmlComments(file.FullName);
    });
    //**重要：新版本swagger务必使用此方法校正**
    services.AddSwaggerGenNewtonsoftSupport();
}
public void Configure(IApplicationBuilder app, IWebHostEnvironment env)
{
    app.Use(async (ctx, next) =>
    {
        ctx.Request.EnableBuffering();
        await next();
    });

    if (env.IsDevelopment())
    {
        app.UseDeveloperExceptionPage();
    }
    //全局跨域支持
    app.UseMiddleware<AllowDomainCorsHeaderMiddleware>();

    app.UseRouting();

    app.UseAuthorization();

    app.UseEndpoints(endpoints =>
    {
        endpoints.MapControllers();
    });

    //使用静态文件时
    //app.UseStaticFiles();

    app.UseSwagger(c =>
    {
        c.RouteTemplate = "/{documentName}/swagger.json";
    });
    app.UseSwaggerUI(c =>
    {
        c.DocumentTitle = "测试的应用API";
        c.RoutePrefix = "CloudYxtTestApi/doc";
        c.DocExpansion(Swashbuckle.AspNetCore.SwaggerUI.DocExpansion.List);

        c.SwaggerEndpoint("/CloudYxtTestApi/swagger.json", "CloudYxtTestApi名称");
        c.DefaultModelExpandDepth(4);
    });

}

使用DescriptionAttribute作为Description说明，类似SwaggerTag功能(无需Swashbuckle.AspNetCore.Annotations依赖)

在services.AddSwaggerGen中开启

c.UseDescriptionAttributeAsTagDescription();

支持Controller、方法、模型

[Description("用于test的描述")]
public class testController : Controller 
{
        [HttpGet]
        [Description("用于Hello的描述")]
        public string Hello()
        {
            return "Hello World";
        }

        [HttpPost]
        [Description("用于PostHello的描述")]
        public string PostHello([FromBody]request_Hello request)
        {
            return $"Hello World:{request.name}";
        }
}

public class request_Hello 
{
        /// <summary>
        /// ID
        /// </summary>
        public string id { get; set; }
        
        [Description("用于name的描述")]
        public string name { get; set; }
}_

跨域中间件使用

在Startup的Configure中定义

//支持所有域
app.UseMiddleware<AllowDomainCorsHeaderMiddleware>();

//支持一个域名跨域
app.UseMiddleware<AllowDomainCorsHeaderMiddleware>("https://www.domain1.com");

//支持多个域名跨域
app.UseMiddleware<AllowDomainCorsHeaderMiddleware>("https://www.domain1.com,https://www.domain2.com");

上传文件

/// <summary>
/// 上传演示
/// </summary>
/// <param name="id">使用query参数的id</param>
/// <param name="type">使用form参数的type</param>
/// <param name="fileToUpload">文件的表单名fileToUpload，特别注意此处切勿加“[FromForm]”</param>
/// <returns></returns>
[HttpPost]
public messageData<long> PostUpload([Required][FromQuery] string id, [Required][FromForm] string type, [Required] IFormFile fileToUpload)
{
    return new messageData<long>() { data = fileToUpload.Length };
}

过滤器常见用法

在Startup中定义全局错误拦截

services.Configure<ApiBehaviorOptions>(options =>
{
    options.InvalidModelStateResponseFactory = ApiHelperExtend.ApiMessageInvalidModelState;
});

使用ApiMessageLog时，部分信息记录不到时，可在Startup的Configure中增加buffer回写

app.Use(async (ctx, next) =>
{
    ctx.Request.EnableBuffering();
    await next();
});

定义全局的Controller

[Route("Api/[controller]/[action]")]	//API路由
[ApiController]                         //声明为API控制器
[ApiMessageLog(ApiName = "Api名称")]	//API日志名称
[ApiMessagePackage]                     //使用code、message包装输出结果
public class extController : ControllerBase
{
}

演示的demo控制器，继承自extController

/// <summary>
/// 演示
/// </summary>
[OpenApiTag("demo", Description = "演示")]
public class demoController : extController
{
    /// <summary>
    /// 获取数据，并按code、message包装输出结果
    /// </summary>
    /// <returns></returns>
    [HttpGet]
    public async Task<messageData<response_class>> GetSomething()
    {
        var data = await......;

        if (something wrong) 
        {
            //抛出code、message错误信息
            throw new ApiMessageException(1, "错误提示");
        }

        return new messageData() { data = data };
    }

    /// <summary>
    /// 使用自定义包装、自定义状态码的输出
    /// </summary>
    /// <returns></returns>
    [HttpPost]
    [ApiMessageTException]      //自定义错误message
    [ApiMessagePackageIgnore]   //不使用code、message包装
    public async Task<response_result> PostSomething([Required][FromBody] request_something request)
    {
        var data = await......;

        if (something wrong) 
        {
            //抛出402状态码的错误信息
            throw new ApiMessageTException<response_result>(类实例变量, 402);    //402状态码
        }

        return new response_result();
    }

    /// <summary>
    /// 获取当前服务器时间相对1970-1-1的毫秒数
    /// </summary>
    /// <returns></returns>
    [HttpGet]
    [ApiMessageLogIgnore]       //忽略API日志
    [ApiMessagePackageIgnore]   //忽略使用结果包装
    public string GetMillTimer()
    {
        return $"{DateTime.Now.toMillTimer():F0}";
    }

}

ApiMessageAuthorization权限检测Filter

注意权限检测需加在方法上

权限认证成功后自动编写context.HttpContext.Items["userId"]

默认认证回调检查方法为用户自定义实现protected object mApiAuthorization(string Policy, string Roles, string AuthenticationSchemes, ActionExecutingContext context, string Scheme, string Parameter)

在WEBAPI中可通过User.Identities.FirstOrDefault(m => m.AuthenticationType == "Scheme")?.BootstrapContext获取权限检查成功的用户信息

例：

//权限验证
protected object mApiAuthorization(string Policy, string Roles, string AuthenticationSchemes, ActionExecutingContext context, string Scheme, string Parameter)
{
    //AuthenticationSchemes
    if (!string.IsNullOrEmpty(AuthenticationSchemes) && !AuthenticationSchemes.Split(',').Contains(Scheme))
        throw new ApiMessageException(4020, "不允许的权限协议", $"{Scheme} not in ({AuthenticationSchemes})");

    if (Scheme == "PRC1")
    {
        //验证用户
        var userTag = ......;
        
        return userTag;
    }
    else if (Scheme == "PRC2")
    {
        //验证用户
        var userTag = ......;
        
        return userTag;
    }

    //验证未通过则返回空
    return null;
}

//在API中获取用户信息
private ClaimsIdentity _claims;

/// <summary>
/// 获取当前用户验证的Scheme
/// </summary>
/// <returns></returns>
protected string currentUserScheme()
{
    if (_claims == null)
        _claims = User.Identities.FirstOrDefault(m => m.AuthenticationType == "Scheme");

    if (_claims == null)
        return string.Empty;

    return _claims.NameClaimType;
}

/// <summary>
/// 获取当前用户验证的用户信息
/// </summary>
/// <typeparam name="T"></typeparam>
/// <returns></returns>
protected T currentUserTag<T>()
{
    if (_claims == null)
        _claims = User.Identities.FirstOrDefault(m => m.AuthenticationType == "Scheme");

    if (_claims == null || _claims?.BootstrapContext == null)
        return default(T);

    return (T)_claims?.BootstrapContext;
}

//支持PRC1,PRC2的权限协议，并且Roles为0才可访问
[ApiMessageAuthorization(AuthenticationSchemes = "PRC1,PRC2", Roles = "0")]
public async Task<messageData<response_class>> GetSomething() 
{
    //获取当前用户
    var userTag = currentUserTag<用户类>();
    .....
}

基于HttpContext的扩展

var ip = HttpContext.remoteRealIp(); //来源IP
var from = HttpContext.remoteFrom(); //来源URL
var agent = HttpContext.remoteAgent(); //来源AGENT

NSwag常见定义(已弃用)

services.AddOpenApiDocument(c =>
{
    c.Title = "WebApi";
    c.Version = "v1";
    c.Description = "WebApi说明";

    c.RequireParametersWithoutDefault = true;
    c.DocumentName = c.Title;
    c.SerializerSettings = new Newtonsoft.Json.JsonSerializerSettings() { ContractResolver = new Newtonsoft.Json.Serialization.DefaultContractResolver() };

    c.AddSecurity("Authorization", new NSwag.OpenApiSecurityScheme()
    {
        Description = "在下框中输入请求头中需要添加授权信息，格式：“{协议版本} {token}”（注意两者之间是一个空格）",
        Name = "Authorization",
        In = NSwag.OpenApiSecurityApiKeyLocation.Header,
        Type = NSwag.OpenApiSecuritySchemeType.ApiKey
    });

    //将控制器Summary显示为描述
    c.UseControllerSummaryAsTagDescription = true;

    //标记ApiMessageAuthorization为需授权接口
    c.OperationProcessors.Add(new ApiMessageAuthorizationNSwagProcessor("Authorization"));
});